Creating Content Library applications

Introduction

In this section you will learn how to create simple hello-world application which can be run on your TV-set.

To simplify this description, we assume that we're creating an application for LE40B650T2W model. (Other model's owner can update this how-to later)

*** THIS WIKI PAGE IS UNDER CONSTRUCTION ***

What is Content Library application?

This is a piece of software that may be run using Content Library feature. To run such application you can call Content Library using CONTENT button, then select Game category, and finally, execute selected application. An example of such application is "WiseStar" game provided by Samsung in their B650 TV-set.

Requirements

• TV-set with Content Library feature and accessible Game category (LE40B650 for example)
• PC with Ubuntu Linux on ~15GB HDD partition (advanced users can use other systems or other compiling toolchain environment)
• Text editor with UTF-8 encoding (gedit for example, which is built-in many linux distributions, also in Ubuntu/Gnome)
• Basic skills of programming in C/C++ language and using GCC compiler

How an application looks like

Every application (or Game) consist of at least one binary file (dynamically loaded library file with .so extension, helloworld.so for example), one XML description file (clmeta.dat) and an icon (usually png graphics with relatively low resolution).

If you want to load your application without Content Library (using injectso method for example), you will need .so file(s) only.

Good practice is to place each application inside a directory called with application's name. For example, our HelloWorld application's files could be:

HelloWorld         <DIR>
   clmeta.dat      <file>
   helloworld.png  <file>
   helloworld.so   <file>

where clmeta.dat file content is:

<?xml version="1.0" encoding="utf-8"?>
<contentlibrary>
  <contentpack id="HelloWorld">
    <category>Game</category>
    <title language_id="English">HelloWorld</title>
    <startpoint language_id="English">./helloworld.so</startpoint>
    <thumbnailpath>./helloworld.png</thumbnailpath>
    <totalsize>1</totalsize>
  </contentpack>
</contentlibrary>

English language is set here. You can prepare different binary modules for different languages. In this example above English version will be used always, regardless on the menu language setting.

All editable text strings have been marked bold. Other entries should remain unchanged. Totalsize value seems to be not used by TV-set.

Note that main binary file (helloworld.so), pointed in clmeta.dat file and loaded by Content Library is not a simple executable file. It is a dynamic library with Game_Main() function which is called first.

Preparing compiling toolchain environment

To be able to create binary file, you must have so-called compiling toolchain. In a simple words, it is a compiler for your source code. Its task is to convert source code text files of your application to the machine code binary files which could be run on TV's CPU. We will prepare so-called cross-compiling toolchain here, which will be able to create ARM executable code on other platform (x86). Although internet connection is required during installation process, you will be able to compile your applications completely offline.

You can study how to build cross-compiling toolchain by reading this forum thread, but you can do it much easier by using our special scripts for Linux Ubuntu. Here are details how to install cross-compiling toolchain that way:

• 1. Download and install Linux Ubuntu (the scripts are designed for Ubuntu 10.04 LTS)
• 2. Setup root account password using this command:

sudo passwd root

• 3. Update your system by calling this command:

sudo apt-get upgrade

NOTE: Internet connection is required for this step!

• 4. Download these scripts to any directory (for example for user's home directory).
• 5. Place 32B650.zip file (the archive released previously by Samsung) with the scripts.

This archive should contain the following files:

libgphoto2-2.3.1.tar.zip
libusb-0.1.12.tar.gz
linux.chelsea.tgz
SDL-1.2.11.zip
SELP.3.2.x-Chelsea.src.tgz

NOTE: 09_LE32B650.tar.gz file from Samsung Open Source Release Center (browse TV & Video, TV, LCD section) is not compatible with these scripts.

• 6. Download thsese 7 files:

freetype-SamyGO-v0.01.tgz
png-SamyGO-v0.01.tgz
SDL-1.2.14-SamyGO-v0.03.tgz
sdl-image-SamyGO-v0.01.tgz
sdl-mixer-SamyGO-v0.01.tgz
sdl-ttf-SamyGO-v0.01.tgz
zlib-SamyGO-v0.02.tgz

and copy them to devel subdirectory

• 7. Open linux terminal window (console) and call ubuntu_install_first.sh script using root account:

sudo ubuntu_install_first.sh

Then wait for script do end its execution (it could last for several minutes). It should write "DONE." on exit.

NOTE: Internet connection is still required here. The script will download some missing packages.

• 8. Call ubuntu_install_addons_arm.sh script:

sudo ubuntu_install_addons_arm.sh

This step will install some SDK libraries required for compiling SDL applications etc.

• 9. Call ubuntu_install_addons_x86.sh script (optional step):

sudo ubuntu_install_addons_x86.sh

NOTE: This step will allow you to compile your SDL applications for x86 platform for testing purposes. Internet connection is still required here. The script will download some missing packages.

• 10. You're almost done. Now you can create a subdirectory in your user's home directory (I mean, not root's but raw user's). I prefer SamyGO directory name:

mkdir SamyGO
cd SamyGO

This subdirectory will be the home for all your projects.

To start a new project (create a new application), go into SamyGO directory created here, then create a new subdirectory inside.

Example #1 - very simple application

First, create HelloWorld1 subdirectory for our new application. Then go inside:

mkdir HelloWorld1
cd HelloWorld1

Create new text file - helloworld1.c - for example by using gedit text editor:

gedit helloworld1.c &

then write and save such simple contents:

// HelloWorld1 - example application #1

#include <stdlib.h>

// main function
int Game_Main(const char *path, const char *udn __attribute__ ((unused)))
{
   system("touch /mtd_ram/HelloWorld1_was_here");

   return 0;
}

This application creates an empty file called HelloWorld1_was_here in /mtd_ram directory when called. It does nothing more. Note Game_Main() function is the main function for a Content Library application. It's first attribute (path) contains a full path to that application and can be used later. There is no main() function here.

Now, let's make binary file which could be executed in Content Library. Create a script (make.sh) with such commands:

# main parameters:
APPNAME="HelloWorld1"
FULLAPPNAME="Hello World 1"
MODULENAME="helloworld1"

# compiler/linker parameters:
CC=arm-SamyGO-linux-gnueabi-gcc
CFLAGS="-O2 -Wall"
LDFLAGS="-s -shared -Wl"


echo "Compiling..."

mkdir -p pendrive/$APPNAME
$CC $CFLAGS -c $MODULENAME.c -o $MODULENAME.o
$CC $LDFLAGS -o pendrive/$APPNAME/$MODULENAME.so $MODULENAME.o

echo "Creating clmeta.dat..."
echo '<?xml version="1.0" encoding="utf-8"?>' >pendrive/$APPNAME/clmeta.dat
echo '<contentlibrary>' >>pendrive/$APPNAME/clmeta.dat
echo '  <contentpack id="console">' >>pendrive/$APPNAME/clmeta.dat
echo '    <category>Game</category>' >>pendrive/$APPNAME/clmeta.dat
echo '    <title language_id="English">'$FULLAPPNAME'</title>' >>pendrive/$APPNAME/clmeta.dat
echo '    <startpoint language_id="English">./'$MODULENAME'.so</startpoint>' >>pendrive/$APPNAME/clmeta.dat
echo '    <thumbnailpath>./'$MODULENAME'.png</thumbnailpath>' >>pendrive/$APPNAME/clmeta.dat
echo '    <totalsize>1</totalsize>' >>pendrive/$APPNAME/clmeta.dat
echo '  </contentpack>' >>pendrive/$APPNAME/clmeta.dat
echo '</contentlibrary>' >>pendrive/$APPNAME/clmeta.dat

rm ./*.o
echo "Application files:"
ls -l pendrive/$APPNAME/*

Make this script executable by command:

chmod u+x make.sh

Then run it by calling:

./make.sh

You'll see such text output:

Compiling...
Creating clmeta.dat...
Application files:
-rw-r--r-- 1 user user  355 2011-11-10 11:41 pendrive/HelloWorld1/clmeta.dat
-rwxr-xr-x 1 user user 3159 2011-11-10 11:41 pendrive/HelloWorld1/helloworld1.so

It means that the script created binary file (helloworld1.so) and clmeta.dat file as well. There is one file missing in pendrive/Helloworld1 subdirectory. Do you know which? Yes - a bitmap. You must create a logo file (HelloWorld1.png) and place beside clmeta.dat file. Or you can use this ready-made picture:

Our application is now ready to run. Copy the whole HelloWorld1 subdirectory (located inside HelloWorld1/pendrive directory) to a pendrive, then connect this pendrive to your TV. Call Content Library and execute our new "Game" called "Hello World 1". All you will see is a second of blackness. It means that our application has been executed and returned immediately. So check if there is /mtd_ram/HelloWorld1_was_here file present there by using telnet of FTP session. It should exist.

Example #2 - using SDL and remote control buttons

Now we are going to create an application which will display a bitmap after pressing a button. This is a very different application than example #1 because it must stay resident in memory and wait for user's action. There is also one more challenge: it is going to use SDL (Simple Direct Layer) do draw on the screen. Using these techniques you can make many useful applications.

Again, let's create a subdirectory for this new project

mkdir HelloWorld2
cd HelloWorld2

TO BE CONTINUED...

(PLEASE CORRECT MY ERRORS)