event-osd Tutorial

This is a simple tutorial that guides you through the steps of creating your own GUI modifications with event-osd for the Western Digital TV HD (WDTV). This tutorial assumes a basic knowledge of Linux and Shell scripting, i.e. you should know or at least have heard of commands like ls, chmod and sed.

At the end of this tutorial we will have an OSD mod that displays the current directory name at the top of the screen as shown so subtly in the following screenshot.

Prerequisites

You must have a firmware that supports event-osd, so either ext3-boot or WDLXTV. Then of course you need the latest version of the event-osd application image). Simply download, extract it and copy the "event-osd.app.bin" to your USB stick for the WDTV.

The Script

event-osd calls a shell script in an event whereas an event currently is a directory change. The shell script is called BEFORE the event occurs, so the shell script can modify any OSD files to change the UI displayed by the WDTV. The OSD files the script can modify are NOT the ones in /osd. The working copy of the OSD files is in /apps/event-osd/osd-backup/. All scripts must modify the files there.

The shell script is passed two parameters that identify the state of the GUI. The first parameter is the current browse mode which is either list mode or thumb mode, depending on the user's configuration. The second parameter is the directory the user changed to.

The following shell script will be used by this tutorial to modify the OSD, it is explained below.

#!/bin/sh
#
# A sample script for event-osd that displays the current path on the top of the screen.

mode=$1     # either thumb or list
newpath=$2  # the directory, "escaped" with double quotes, so when passing this on to another command put it in double quotes as well

if [ $mode = "thumb" ] ; then
    filename=basic_browse_thumb_video.xml
else
    filename=basic_browse.xml
fi


directory=`basename "$newpath"`           # note the "" around $newpath
sed -e 's/.*<\/page>/<text text="PLACE" fontsize="40" textcolor="0xffffff" x="0" y="0" w="1280" h="100" \/><\/page>/' \
    -e s/PLACE/"$directory"/ \
    -i /apps/event-osd/osd-backup/$filename
echo "sleep 2 && sed -e 's/.*<\\/page>/<\\/page>/' -i /apps/event-osd/osd-backup/$filename" | sh &

• At first the parameter are put into more descriptive variables. Please note that the mode parameter is either list or thumb, depending on the WDTV's configuration. And note further that the newpath parameter is not escaped but instead passed as a quoted parameter. This means when you use the path and pass it on to another command you must enclose it in quotes ("") as well. The tutorial makes use of this later.
• Next the script determines the main file used by the OSD to display the directory contents. This depends on whether the user selected to browse his movies in list or thumbs mode.
• The line directory=`basename "$newpath"` is used to extract the current directory name from the absolute path, so from "/foo/bar" we get "bar".
• The ugly looking sed command that follows simply does a replacement in the OSD XML file determined in the first second step. It adds a text element at the end of the XML file that displays the current directory name. This is done in two steps, first the actual XML element is inserted and then the directory name replaced. This has to do with sed semantics and can probably be done in a dozen different ways. At the end of this step the last line of the XML file is converted from </page> to <text text="bar" fontsize="40" textcolor="0xffffff" x="0" y="0" w="1280" h="100" /></page> (in case the directory is "bar").
• Finally, the last command starts a background process that waits two seconds and then restores the original XML file by removing the inserted text element. If the restore operation is more complex its probably easier to move this part to another shell script and execute it in the background.

OK, now that the script is explained lets test it. Create a file with the scripts content somewhere on your WDTV, for example at /opt/tutorial_dir_changed.sh. Remember to make the file executeable

# chmod 755 /opt/tutorial_dir_changed.sh

Its always a good idea to test things before moving on, so give it a try:

# /opt/tutorial_dir_changed.sh list "/I/made/this path up/" && cat /apps/event-osd/osd-backup/basic_browse.xml

<?xml version="1.0"?>
<!-- Copyright (C) 2007, ALPHA Networks, inc. -->
<page background="image/welcome_background_bg.jpg" type="basic">

[...]

  <include filename="./decoration.xml"/>
<text text="this path up" fontsize="40" textcolor="0xffffff" x="0" y="0" w="1280" h="100" /></page>

And then after a few seconds lets make sure that the file is indeed restored correctly:

# cat /apps/event-osd/osd-backup/basic_browse.xml

<?xml version="1.0"?>
<!-- Copyright (C) 2007, ALPHA Networks, inc. -->
<page background="image/welcome_background_bg.jpg" type="basic">

  [...]

  <include filename="././inc_headline_property.xml"/>
  <include filename="./decoration.xml"/>
</page>

If the tests are successful we can move on to the next part, otherwise check your shell script.

Please note that this part must not be a shell script, it can also be a compiled C program or a Perl or Python or whatever script. However, since Perl, Python and so on take a relatively long time to start on the WDTV its not a good idea to call such a script again and again on a directory change. If you want to use for example Python to modify the UI, I recommend you write your main application as a server that listens for commands on for example a TCP port or another socket. The server is started in the background and then fed the events and parameters from a shell script.

app.event Configuration File

At last but not least we create an app.event configuration file for event-osd. app.event files are used to tell event-osd which scripts to execute and when. They must be placed on the boot USB stick, so at the same directory as the event-osd.app.bin.

Create a configuration file like the following one and copy it onto the USB stick to e.g. tutorial.app.event:

You can also edit it directly on the stick, on ext3-boot simply put the file into /boot/.

version=1
pattern=/
script=/opt/tutorial_dir_changed.sh

The format is easy: parameter=value. Each parameter is described in more detail in the following points:

• version: used to identify the version of the configuration file. This parameter is currently unused but will be used later to provided backward compatibility.
• pattern: used to determine whether this configuration file is relevant for the changed directory. If the directory does not contain the pattern the script associated with the configuration file is not executed. The pattern is a simply string match, so if you use "/" as a pattern every directory matches, if you use "/My Movies/" only paths that contain the "/My Movies/" string are a match. The pattern is case sensitive.
• script: this is the script / program that is executed when the pattern matches. The value must be an absolute path.

So, if necessary adapt the script's path to match yours and copy the file to your USB stick.

Finally reboot your WDTV and navigate through the directories. Note: It only works when browsing movies and not in the root directory.

Troubleshooting

If something does not work, you can have a look at the /apps/event-osd/event_osd_fs.log file and look for ERROR messages. Most likely your configuration is not picked up, look at the first lines in the log file and see if it is loaded.