Introduction to LIRC and Set-Top Box Mode top

Moving away from the Desktop ...

Watching DVB TV with a Linux desktop system has become quite trivial, a lot software was written to support this, including Kaffeine, Xine and MPlayer. Less trivial was the use of a computer as a video recorder, but once more there is software like ZapDvb to simplify this concern. The real challenge is building a Set-Top Box. And over again several Linux projects take care of this (see www.linuxtv.org/wiki). ZapDvb is among them and is centered around two paradigms (1) support for DVB only and (2) run with cheap hardware (e.g. no special MPEG cards).

LIRC - Using a Remote Control

Keyboard and mouse are not the perfect input devices for a set-top box - a remote control (RC) would be desirable. Today most RCs still use infrared light (IR). Fortunately the Linux LIRC project furnishes a good driver frame work for this. It is highly recommended to configure LIRC, even for a desktop system that is frequently used to watch TV. ZapDvb supports LIRC fairly well (since version 0.43), but it cannot supply the configuration files for your Remote Control.

Besides creating the required configuration file (LIRC contains a tool called irrecord that takes care of this job), you will need some hardware (transmitter and receiver). Consult the LIRC documentation or a search engine for details. Luckily some cheap DVB cards come with an IR control and a dongle for the PC. Please do not confuse LIRC and IRDA, the first uses a low data rate to transmit single key strokes, the later uses a much higher data rate for file transfer and other things.

Often you will be able to re-use the remote control of the TV monitor. These have often unused buttons or shift levels for hardware that you do not own or don't use. Most hardware will work fine with LIRC (some are tricky, the data folder contains an example for Acer, see global.acer.com/products/lcd_tv). B&O remote controls cannot be used directly, they use an uncommon frequency (with excellent results, see www.bang-olufsen.com). A converter could help, see www.irtrans.de. Acer, B&O and irtrans are trademarks of manufacturers that have no direct relation to ZapDvb, they got mentioned for informational purposes only.

Build your own Set-Top Box

In this context a set-top box is a computer that is primarily used to provide TV and other multi-media data and that is usually connected to a TV monitor. Additional functionality like WEB browsing or E-Mail is free (via KDE). The first things that you need are hardware:

• A simple PC like a bare bone (for less than 500€ including CPU, memory, disk and DVD).
• The PC can be equipped with a DVB card (50-60€) or it could share a card in a server (see ZapDvb's Remote Mode).
• A TV style LCD monitor with attached speakers (800-1200€). The monitor is as important as the PC - often cheap TV sets are good monitors. Analog TV sets work too but need a PC with tv-output.

Your investment for the whole project would should range from 1200€ to 1500€ and not more. It makes little sense to spend more money, often more expensive equipment is less common causing driver support problems (usually programmers don't get rich from working on Linux).

The software for this PC should be a free Linux distribution (Debian Sarge and SuSE 9.3 are known to work) and ZapDvb. Given that it works in desktop setup and that the TV monitor is a LCD connected via DVI: the ZapDvb set-top mode should work just out of the box. Even if set-top box mode is configured, the PC can still be used as a desktop: ZapDvb uses run level 4 (which is other wise unused) and you are free to boot it as a desktop system in level 3 or 5.

The set-top box mode depends on KDE: important KDE goodies include the kwin windows manager, internationalisation and, less important, some player/viewer tools. In contrast to the remainder of the ZapDvb project, which will support other desktops too, the set-top box mode will only work with KDE and take advantage of KDE's great infrastructure.

IMPORTANT HARDWARE TIPS

1. Currently a lot of LCD TV-sets with a physical resolution of only 640x480 pixels are offered. These are good for the American and Japanese markets only (NTSC) as they cannot cover the higher TV resolution used elsewhere (PAL). DON'T BUY - this crap does not serve well as a PC screen.
2. You should really insist in using DVI. The LCD Monitor and the Bare-Bone PC (or whatever you use) should support this standard to obtain the best image quality. Try to get one with a 15:9 aspect ratio - a good compromise.
3. Don't buy expensive equipment! You will need only a simple PC, a 2.4 GHz Celeron even with a cheap chip set and 256 MByte will work fine. Integrated graphics should be fine but some SiS chips sets may cause trouble with AMD CPUs, see www.winischhofer.net.
4. More important is the monitor, but even the cheap ones (that are sometimes lousy TV-Sets) can be excellent as Computer Displays.

 How to use LIRC with ZapDvb top

Installing LIRC

Start the work by installing the LIRC packet and by reading the documentation (/usr/share/doc/lirc/html on Debian). SuSE provides some documentation on how to modify boot.local and a sysconfig file in an extra README file. SuSE users might take these steps to configure LIRC for a simple RS-232 dongle on /dev/ttyS0:

# SuSE (1) Entries in /etc/sysconfig:

    LIRC_MODULE="lirc_serial"
    LIRC_DEVICE="/dev/lirc"
    LIRC_DRIVER="default"

# SuSE (2) Modifications to /etc/boot.local:

    setserial /dev/ttyS0 uart none
    modprobe lirl_serial

# SuSE (3) Create /etc/lirc.conf:

    # That file describes the protocol and the keys of a remote control.
    # If you cannot find an existing config make your own using irrecord

# SuSE (4) Check the sym links (little bug: lircm missing?),
#          SuSE wants fifo and device files to live in /var/run/lirc
    cd /dev
    ln -s lirc0 lirc                 # should have existed
    ln -s /var/run/lirc/lircd lircd  # should have existed
    mkfifo /var/run/lirc/lircm       # missing?
    ln -s /var/run/lirc/lircm lircm  # missing?
    chmod 666 /var/run/lirc/lircd /var/run/lirc/lircm

# SuSE (5) Install the wmctrl package from the DVD or a mirror like
#          http://ftp.gwdg.de/pub/suse/i386/9.3

To adjust file protections and to unload the LIRC drivers Debian users will prepare LIRC by doing something like:

# Debian (1) Install setserial and wmctrl:

    apt-get install setserial wmctrl

# Debian (2) Tweak /etc/lirc/hardware.conf to contain:

    setserial /dev/ttyS0 uart none
    [ -e /dev/lirc ]  || ln -s /dev/lirc0 /dev/lirc
    [ -e /dev/lircm ] || mkfifo /dev/lircm
    chmod 666 /dev/lircd /dev/lircm

    if [ "$1" = "start" ] ; then
       setserial /dev/ttyS0 uart none
       [ -L /dev/lirc ]  || ln -s /dev/lirc0 /dev/lirc
       [ -e /dev/lircm ] || mkfifo /dev/lircm
       chmod 660 /dev/lirc?
       chgrp video /dev/lirc?
    elif [ "$1" = "stop" ] ; then
       # only reloading the driver allows to "plug in" other hardware
       trap "rmmod lirc_serial 2>/dev/null ; rmmod lirc_dev 2>/dev/null" 0
    fi

    LIRCD_ARGS=""
    LOAD_MODULES=true
    DRIVER="default"
    DEVICE="/dev/lirc"
    MODULES="lirc_serial"

# Debian (3) Create /etc/lirc/lircd.conf:

    # That file describes the protocol and the keys of a remote control.
    # If you cannot find an existing config make your own using irrecord

The wmctrl package contains a little tool to interact with the X11 window manager and is currently used by zapmcc (this may change in future). In Debian setserial is a package of its own and is not installed by default. This tool is used to stop the built-in kernel drivers sitting on the serial port that is connected to the IR dongle (the example assumes ttyS0).

zapmcc will try to launch the LIRC daemons by itself. The setup program should have been allowed to add an entry to /etc/sudoers to make this possible:

# allow group members and zapdvb to start LIRC
%video,%audio,zapdvb ALL=NOPASSWD: /etc/init.d/lirc start

Make sure that the user zapdvb (or the video group) have the right permissions to read/write from /dev/lircd and /dev/lircm. Only zapdvb_box does this automatically when you start in set-top box mode. But LIRC is still disabled by default. You need to make two symbolic links (or to create your own files) that depend on your remote control:

# First test your LIRC configuration with the irw tool:

    /etc/init.d/lirc start
    irw         # when you press a RC key the tool should spit out
                # a line telling you what happened, stop with Ctrl-C
    /etc/init.d/lirc stop

# here we use the lirc_simple example ...
    cd /usr/local/share/zapdvb/config
    ln -s ../data/lircex_simple.conf lircex.conf  # this is mandatory
    ln -s ../data/lircmd_simple.conf lircmd.conf  # this is optional

The two files just mentioned contain definitions for LIRC actions (lircex) and for the LIRC mouse emulation. You will have to adjust these example files to match your remote control. If you want to use LIRC in desktop mode (at least for testing) you should call zapmcc with the --lirc option. Some usage examples:

# start the media control center
    zapmcc --lirc --nowait          # now it runs in background

# send some actions (LIRC does this in a very similar way) ...
    zapmcc --tv                     # show the tv menu
    zapmcc --cancel                 # close the current menu
    zapmcc --cancel                 # close zapmcc

When LIRC is enabled ZapDvb changes it's GUI slightly to become more usable without a mouse. The zapdvb.conf file gives you some control about this, see menumode. In a pure desktop environment you should consider to omit the --lirc option when launching zapmcc via menu shortcuts.

The LIRC Tools and a Bug in irxevent

From the text above you know that ZapDvb currently uses some of the tools that come with the LIRC package. An additional package (Debian) is lirc-x which contains irxevent and the xmode2 tool:

# Required programs from lirc are:
   lircd       # the main LIRC daemon (zapmcc tries to start it if needed)
   lircmd      # the mouse daemon     (zapmcc starts it if configured)
   lircex      # command execution    (zapmcc starts it)

   irrecord    # learns IR commands   ('setup lirc' can run it)  **
   irw         # dumps IR commands    ('setup lirc' can run it)  **

# Optional programs from lirc-x are:
   irxevent    # sends key strokes to applications (SEE BELOW...)
   xmode2      # displays a signal diagram of received raw data  **

# ** These tools can be useful during settup but are not used by zapmcc

Unfortunately the irxevent tool is broken (SuSE 9.3 and Debian SID, bug reported 2005-09-07). The config folder of ZapDvb should contain a patched version that works better (get it from the download page). Simply delete the config/irxevent file if it causes problems or if the LIRC people repair their version. The symptom of the bug is that irxevent sends every key stroke to the active window if it cannot find the application to which the key should have been sent.

The Configuration, using 'setup lirc'

ZapDvb comes with quite elaborated LIRC support. To keep the configuration simple it uses a little tweak: the hardware description file /etc/lirc/hardware.conf (Debian) should not contain key labels but the ZapDvb defined action names. Addional user-level configuration is handled via zapdvb.conf. Before we get lost in details simply try one of the examples (even if it does not work with your remote control. Please do not select custom/native now):

cd /usr/local/share/zapdvb
./setup lirc
ZapDvb comes with 3 example configurations. Please select 'custom'
if you want to use a RC that does not match one of the examples...
1) technisat (22 buttons came with SAT receiver)
2) skystar   (33 buttons came with DVB card)
3) acer      (52 buttons came with LCD TV set)
4) custom    (use irrecord to configure this)
Please enter a number to select a configuration: 1

Now select a mode.  To keep things simple do not use 'native' which
uses states and is intended for computers without keyboard/mouse...
1) simple    (no shift keys - no LIRC defined states)
2) native    (using shift keys for mouse/zapmcc)
3) custom    (custom config for lircex and lircmd)
Please enter a number to select a mode: 1

LIRC can emulate a mouse. Enable this feature [y/n] y
restarting LIRC ...
Stopping lirc daemon: lircmd lircd.
Starting lirc daemon: lircd.
Run the 'irw' program to test your configuration [y/n] y

    WARNING: As you press RC buttons output lines should be printed.
             Exit the program with CTRL-C ...

Don't worry if it does not work with your remote control! At the moment you should have a look at the config/lirc* symbolic links to see how the predefined action codes are used. Now try to assign these codes to the buttons of your remote control (ignore the button labels). Next step is to run the setup lirc a second time now specifying custom as RC type (1. question). Still select simple in the 2nd question. The programm will create an empty hardware description file and then runs the irrecord program which will guide you through the process of learning the codes of your remote control. When finished irw should now report button presses.

Possible problems: (1) Make sure that your receiver works and is correctly configured. It might help to connect the receiver to its RC232 port before booting Linux. Use the xmode2 tool to watch the raw signal that gets received. Try different remoted controls. Some of them wan't work at all because they use unusual frequencies. If xmode2 can display the signal your chances are good to make LIRC work.
(2) The LIRC drivers auto-detect the IR receiver type once at load time. To change the receiver hardware later or simply if you connect the dongle after having booted you must re-load the drivers.
(3) In some cases irrecord does not detect the protocol used by your hardware (the Acer RC is an example). LIRC comes with a number of generic configurations that you can use as a starting point (try them one after another until you find one that works). If everything fails you could still try to run your hardware in raw mode.
(4) LIRC uses the carrier detect signal of the RS232 port to read data at a relatively high data rate (in respect to the RS323 specs). This causes noise problems with long unshielded cables. Use short and shielded cables instead, use xmode2 to see it the signal contains noise.

If you want to create your own problems: LIRC can use internal states and assign different actions to keys depending on the internal state. Unfortunately LIRC knows very little about the applications that it controls. In contrast to this ZapDvb has more control over its components and manages states internally (this is the simple mode that we used until now). With native mode you can add states to your LIRC configuration and still use ZapDvb. As an example you could toggle the key used for mouse emulation (if you RC has very few buttons like example #1) or you can temporarily disable the ZapDvb actions to control something else (other applications or hardware). These are advanced features, please make sure that you understand the simple and native mode before experimenting with custom (which just creates an empty file for your own definitions, good luck).

User defined actions in zapdvb.conf

Don't hard code custom program calls into your LIRC configuration, it is preferable to use the exec actions as they can be mapped to something useful via zapdvb.conf, see section [zapgop] for some examples. Currently (version 0.43) only very limited functionality is available, but this will change in future versions. You will be able to define exec actions that depend on ZapDvb's internal states (examples of states are: tv, radio, cd).

 Using the setup Program to Configure Set-Top Box Mode top

In Installation and Configuration (README_INSTALL) the setup program was introduced and the first two of three configuration steps were documented. Here the third step titled "add the settop box features" will be discussed. The following points are important:

• In step 1 and 2 you must have answered "yes" at least to the questions 1,2,3 and 5. If you did not then please run these steps again (try "./setup config" without any extra argument).
• The set-top box mode uses run level 4, see /etc/inittab. This file and the corresponding start up links will be modified (can be un-done, see "./setup unconf").
• Your boot loader must be configured to boot into run level and to launch zapdvb_box. The setup program cannot do this directly. You can do this work later, there is an easy way to test the set-top box mode from run-level 1.
• When everything works and after you have made a backup then try to optimise the system. To reduce the boot time of the computer all unneeded services should be removed from rcS (and rc4). The data folder contains some example configuration files - but you have to find out for your hardware what can be removed.

su                              # must run as super user
cd /usr/local/share/zapdvb      # change to the installation folder
./setup confing box             # the 3rd step: set-top box mode

This is configuration part 3: add the settop box features
=========================================================

(8) replace /etc/inittab [y/n] y

    WARNING: The original /etc/inittab was saved as /etc/inittab.debian

(9) replace run-level 4 startup scripts [y/n] y

    DO NOT FORGET: remove unneeded services from /etc/rcS_d
                   See the example: data/debian/rcS_d.tgz

(10) You should now update /boot/grub/menu.lst to boot into runlevel 4 [y/n] y

    YOU HAVE TO DO THIS MANUALLY! See an example below:

    title ZapDvb Set-top Box Mode
       kernel (hd0,2)/boot/kernel root=/dev/hda3 vga=0 desktop 4

    Run 'editor /boot/grub/menu.lst' now [y/n] y

Settop box configuration completed.

Testing Step 1: Start the Set-Top Mode from Run-Level 1

This is the best way for testing. Please switch the run-level (type "sudo /sbin/init 1" and login as root). You can try your first steps using the VESA driver for X11. If you want to use analog tv output later please do not start with that, use a computer monitor instead and if everything else runs fine try to make tvout work:

# select the VESA driver for testing ...
  cd /usr/local/share/zapdvb/config
  ln -s ../data/xf86deflt.conf xserver.conf

# run the test ...
  cd /usr/local/share/zapdvb
  ./zapdvb_box --fake

# if nothing happend try to force a full KDE start ...
  cd /usr/local/share/zapdvb
  ./zapdvb_box --full

Now the X11 server should start, a friendly desktop wall paper will show up and if you are lucky a KDE session should start. This is probably not what you expected, but this happens the first time only.

Testing Step 2: If the X11 Server does not run

There should be a log file in /usr/local/share/zapdvb/xserver.log try to make X11 happy and go back to Step1.

Testing Step 3: X11 running but nothing else happens

This effect appears from time to time (usually after upgrading some software). Kill the X11 server (via keyboard Shift-Ctrl-Backspace) and retry Step1 using the option --full instead of --fake. The problem is ugly and future versions of ZapDvb will try to avoid it. Anyhow, it (almost) never happens after your finished changing the system.

Testing Step 4: Find something better than the VESA driver

The VESA driver is not as fast as a hardware specific driver and it does not support all features. Check your /etc/xf86config-4 to see what your hardware driver is. Edit the settings in xserver.config to match your hardware (make a local copy in the config folder, do not edit the original file). Try again with step 1.

Some Details

Why ZapDvb uses a private X11 configuration: (1) an intentionally wrong DPI setting causes X11 to display huge fonts (2) one might adjust the monitor gamma and other parameters (driver dependent) to achieve optimum results for TV display. The preferred settings for a TV display differ significantly from what is optimal for other computer work.

In the data folder you can find xf86deflt and two alternative X11 configurations. Here is why:

• xf86deflt: the bare minimum pre-configured for VESA (always works but is not optimal)
• xf86tvlcd: a starting point for using an LCD TV monitor (here using a SiS or a Radeon chip-set).
• xf86tvout: the starting point for analog TV output (here using a SiS chip-set)

Since version 0.42 of this software it is no longer recommended to use the display=tvxxx kernel boot argument, but if you work with multiple displays for the same computer the feature may be useful: use the display=tvout parameter for a classical TV Set or use display=tvlcd for an LCD display. The display argument causes zapdvb_box to load the appropriate file from the data folder (not the config folder!).

Did you modify your boot manager's config? Here is an example of two lines that can be used for grub (adapt them for your configuration):

title ZapDvb Set-Top Box Mode
    kernel (hd0,2)/boot/kernel root=/dev/hda3 vga=0 desktop 4

The important points were the vga=0 parameter for to avoid problems with the TV monitor and 4 to start in ZapDvb's set-top box mode.

To make run-level 4 work, two steps are required: (1) populate /etc/init.d/rc4.d and add an entry to /etc/inittab:

# tvout mode in inittab
tv:4:wait:/usr/local/share/zapdvb/zapdvb_box

 Tips for Tweaking the Linux System and X11 top

Analog TV Output (tvout)

Do not forget to adjust your xf86tvout.conf if you want to use PAL TV output (connecting a NTSC TV set makes little sense). In any case you should have made working X11 config files for the equipment that you are going to use before. If your PC has a TV output and is connected to a TV set, you can boot with a low screen resolution like 800x600 and then use a tool like sisctrl (SiS driver only) to adjust your settings. Try to get as close to the PAL resolution as you can ("768x576" @ 50 Hz). To watch movies turn of all signal filters (for better sharpness). Carefully adjust the gamma settings (for good colours and gray-scales).

HARDWARE TIP: Your BIOS may refuse to enable TV output if the TV set is not connected at boot time. The SiS driver can re-program the chip-set later (if you tell it), but some other drivers may be unable to do so.

Monitor Gamma

Adjusting the gamma settings is also important for LCD screens. If you did not ask before: we do not use the /etc/XF86Config because we need other gammas for office work than for watching movies. There are tools to do this from inside KDE for example, but it is better (child-safe) not to depend on a tool.

Cheap monitors (for the low-price PC market) usually have a high gamma value. We got used to that when working with PC software (sharp, high-contrast display). But high gammas are bad for watching TV and image processing. Unfortunately LCD monitors have high gammas (due to hardware restrictions). There are some software tools to compensate this in software (most X11 drivers can do this), but this also increases the amount of visible noise. Try out the following:

• Given that your LCD monitor has a gamma of 1.75, tell X11 that it has 1.5 (with higher values you will run into a "noise" problem).
• Configure your player to use a low contrast value. Make it lower as long as black does not turn to gray.
• Adjust the player brightness to a high value, as long as bright areas in the image do not bleach out.
• Save these setting in the player's config file, don't touch them any more.
• Use the controls of the TV set to get the right brightness for day time or night time.

Remarks concerning the SuSE resmgr Daemon

Linux has a problem with it's old fashioned, minimalistic rights attributes in the file-system. POSIX ACLs could be a solution but they are not yet widely used (and I even don't know if POSIX ACLs can be used with devices). In the installation instructions it was suggested to use the groups "video" and "audio" for users that are allowed run ZapDvb. One reason for this was that devices can be owned by these groups so that "video" group member for example can read from the DVB devices. The zapdvb_box script sets the rights of some devices according to this scheme.

The group approach has disadvantages (a device can only be owned by a single group). So SuSE tried to overcome similar problems by introducing the resmgr Daemon - but in set-top box mode this daemon will probably not be required if the rights are set correctly. In a normal desktop system the rules described above would not be easy to follow. SuSE links some programs that use video or sound devices against a library that calls the resmgr daemon when an attempt is made to open such a device. The /etc/resmgr.conf file contains a list of these devices. The daemon, which has root privileges, seems to change the device ownership on the fly so that the library can open the device as expected.

ACPI and Power Management

Consider running the ACPI daemon to allow users to switch the computer off by pressing the power button. Anyhow: in soft-power-off mode most power supplies consume 10 to 20 Watts (the later was measured for a high-price power supply!). This will add about 20€ to your electricity bill - you have been warned.

Power management should be installed if available. If the processor is idle this can reduce the power consumption by 30%. At least the cooling fan will run less often.

 Tweaking KDE for to get Optimal Results top

There are three groups of things that should be discussed here. Most of the stuff is configuration related. The first time that you start in Set-top Box mode zapdvb_box launches a full KDE session: use this to configure KDE (the keyboard for example). Other ways to change the KDE configuration are:

• Change from Set-Top Box to a full KDE session by selection that entry in the Set-Top Box menu.
• Start kcontrol from a console window (the Set-Top Box menu lets you open a console).
• Load a pre-configured theme file (you can create your own, see the KDE theme manager).
• Copy configuration files from another .kde folder (you should know what you are doing).

Internationalisation

After installation you will have some mixed language mode. The file .kde/share/config/kxbrc contains instructions for KDE to use a German keyboard map but kdeglobals says that the default language is English. Use the initial start (which runs KDE in a full session) to adjust these. Let either KDE manage your key-map or edit the X11 configuration. The menu language settings are not derived from KDE but from the system locale. Debian users will like to adjust /etc/environment, SuSE users find a nice playground in /etc/sysconfig. For convenience consider to modify /etc/profile to export your language setting (zapdvb_box does not depend this, but .setup likes it):

# Debian example: you may add this to your /etc/profile:
if [ -z "$LANG" -a -f /etc/environment ] ; then
   set `grep "^LANG=" /etc/environment` --
   export $1
else
   export LANG=de_DE.UTF-8  # put your fall-back locale here
fi

Do not use locales with the @euro suffix, KDE hates this (the Euro sign is part of the UNICODE standard). Non-US users should prefer UTF-8 (UNICODE) based locales (which usually works fine) over ISO8859-15 or similar (which is now outdated but still used by legacy applications).

Theming

Due to the lower effective gamma a well adjusted TV set can use a colour scheme with multiple gray levels. Simple black/gray/white schemes as in use for the desktop are to bright when watching TV at night time.

Tips

In set-top box mode users will not see a desktop - and no task-bar. But the overwhelming majority of KDE (and X11) applications can work well in this environment. As a user you should know that it is still possible to switch between applications using the Alt-Tab or Shift-Alt-Tab keys. If you get really lost you still can change to a full KDE session, which is a menu entry in the GUI, if it is running in set-top box mode.

There is one major problem: some applications try to hide the main window and to wait for activation via the system tray in the task bar. But in set-top box mode there will be no task bar (you could start kicker manually if you really want). So juk, kscd and others must be configured not to use a tray icon!

The example X-Server configuration lies about the screen size to display huge characters. That does not work well with all types of fonts, but the True-Type fonts work fine. You can also use most of the scalable X-Fonts that get installed by default. Many KDE and Gtk applications will be usable even with an old fashioned TV set you will at least be able to manage your files, to read your E-Mail and to do a little bit of Web Browsing. Consider buying a LCD TV Set (with 1024x768 resolution or better).

 Files in the data Folder top

Some of these files are used by ../zapdvb_box or by the ../setup program, others serve as examples. Please make sure that local changes do not break the scripts! Do not modify the original files, in most cases zapmcc will find a copy that you placed in ../config (otionally prefixed with the hostname and an underscore. Example: mycomputer_help_main.html.