Philips SDK Manual

Philips Consumer Lifestyle Connected Displays - Online Services

- 1 -

Online Services SDK

Manual Status: Approved Version: 1.5 Date: 28 April 2008 Author: S.Raaijmakers Category: Confidential Reference: BLP_SDK_MNL


- 2 -

1. CHANGE HISTORY .............................................................................................................................................. 3

2. INTRODUCTION ................................................................................................................................................... 4

2.1. OVERVIEW.......................................................................................................................................................... 4 2.2. DEFINITIONS ....................................................................................................................................................... 5 2.3. REFERENCES....................................................................................................................................................... 5

3. SYSTEM REQUIREMENTS, INSTALLATION AND USAGE ........................................................................ 6

3.1. SYSTEM REQUIREMENTS ..................................................................................................................................... 6 3.2. INSTALLATION .................................................................................................................................................... 6 3.3. USAGE ................................................................................................................................................................ 9

3.3.1. First time use ............................................................................................................................................. 9 3.3.2. Main menu ............................................................................................................................................... 11 3.3.3. Configuration menu ................................................................................................................................. 11 3.3.4. Browser.................................................................................................................................................... 12 3.3.5. Debugging................................................................................................................................................ 12 3.3.6. Updating .................................................................................................................................................. 13 3.3.7. Troubleshooting ....................................................................................................................................... 13

4. DEVELOPING YOUR SERVICE ....................................................................................................................... 14

4.1. INTRODUCTION ................................................................................................................................................. 14 4.2. OVERALL .......................................................................................................................................................... 14 4.3. TECHNICAL....................................................................................................................................................... 15

APPENDIX A - LINUX INSTALLATION ................................................................................................................. 16


- 3 -

1. Change history Version Date Changes

1.5 2008-04-28 Added Linux installation instructions

1.4 2008-04-22 Minor update.

1.3 2008-04-10 Updated for new SDK software

1.2 2008-03-04 Updated for guidelines documentation

1.1 2008-02-18 Corrected VK_OK to VK_ENTER

1.0 2008-02-08 First version.


- 4 -

2. Introduction

2.1. Overview

Welcome to the Online Services Service Development Kit (SDK). This kit will enable you to develop your service for the 2008 Online Services TV-platform. The kit is under development. We strive to bring you new information in the next releases of the SDK. In the mean time, questions can be put on the wiki forum, to which you have been granted access. There, we (Philips Online Services CSP support) will answer these questions, or refer to the part of the documentation where the answer may be found. In its current form, the kit consists of the following parts:

• this manual

• guidelines ; under this category fall: o technical guidelines : how to best develop your service to achieve good performance and

CE-HTML compatibility o design guidelines : how to make the look and feel of your service suitable for viewing on a

TV-screen and using a remote control

• USB stick containing the Online Services SDK software - this is the essentially the browser that will run your service, and is comparable to the platform browser.

• references to further information, such as the wiki and the standard on which the Online Services are based

• some reference services, which show a wide range of possible CE-HTML applications

• requirements o CE-HTML profile : detailing which CE-HTML capabilities are supported on the TV platform,

which not o platform documentation : detailing what the platform supports in terms of e.g. media codecs,

remote control keys, text entry. Documentation and parts of the software which are not yet included in this version of the SDK:

• complete CE-HTML compliancy of the SDK software (virtual key mappings, media object, etc.)

• test and delivery requirements: how to deliver your service for testing and final release Finally, the SDK is targeted towards technical development. As such, some tasks in installing or using the SDK require some technical skill.


- 5 -

2.2. Definitions

CE-HTML Consumer Electronics HTML, part of ANSI/CEA-2014 ANSI American National Standards Institute CEA Consumer Electronics Association DOM Document Object Model GIF Graphics Interchange Format JPEG Joint Photographic Experts Group (compression format) Media object Audio/-video object, part of CE-HTML PNG Portable Network Graphics SDK Service Development Kit USB Universal Serial Bus XHTML Extensible HyperText Markup Language

2.3. References

[1] ANSI/CEA-2014 Web-based Protocol and Framework for Remote User Interface on UPnP™ Networks and the Internet (Web4CE), December 2006 [2] ECMAscript Language Specification (Third Edition), December 1999, ECMA-262.pdf, http://www.ecma-international.org/publications/standards/Ecma-262.htm [3] XHTML 1.0, The Extensible HyperText Markup Language (2nd ed.), W3C Recommendation 26 January 2000, rev. 1, August 2002, http://www.w3.org/TR/2002/REC-xhtml1-20020801 [4] REC-DOM-Level-2-20001113 Document Object Model (DOM) Level 2 Core Specificiation, Version 1.0, http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113 [5] REC-DOM-Level-2-20001113 Document Object Model (DOM) Level 2 Style Specificiation, Version 1.0, http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113 [6] REC-DOM-Level-2-20001113 Document Object Model (DOM) Level 2 Events Specificiation, Version 1.0, http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113 [7] REC-DOM-Level-2-20030109 Document Object Model (DOM) Level 2 HTML Specificiation, Version 1.0, http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109 [8] CR-css-tv-20030514 CSS TV Profile 1.0, http://www.w3.org/TR/2003/CR-css-tv-20030514


- 6 -

3. System requirements, installation and usage

3.1. System requirements

The SDK software runs on a PC. The PC has to fulfill the following requirements :

• Operating system Windows XP or Linux (limited support)

• Minimum memory 512 MB

• 2GHz processor (AMD 64X2, Pentium IV, Core 2 Duo), dual core preferred

• minimum resolution of 1280X1024 @ 16 bits

• keyboard and mouse

• 100MB free disk space

• 1 free USB 2.0 port

• network connection (wireless or wired) It could be that the SDK will run on a PC which does not comply to these requirements. However, no support can be given in that case. It is recommended to dedicate a PC for the SDK software. This will ease development later on. For Windows XP, administrative priviliges are recommended. The software is known to work without administrative priviliges, however some warnings will be displayed. For Linux, there is a file called "linux_setup.tgz" in the root of the USB drive. Please extract this file and follow the instructions in "INSTALL" or in the appendix of this manual. Linux installation requires moderate to advanced knowledge of Linux, and support is limited. The installation process was tested under SUSE Linux 10.0, with GCC 3.4.3 (for Qemu) and GCC 4.0 (for KQemu).

3.2. Installation

The SDK software is delivered on a 1GB USB stick. The following steps are required to install the software:

1. Insert the USB stick in the PC. 2. If autorun is enabled on the PC, the setup screen should come up by itself. If this is not the case,

run the executable "setup.exe" on the USB stick. 3. The following screen will show:

4. Click Next.


- 7 -

5. Read the license agreement and click "I agree" if you understand and agree to this license. If you do not agree, the SDK will not be installed and you will not be able to use it.


- 8 -

6. The SDK will now install. 7. When the installation is complete, the screen below will appear. The software is now installed, click

finish to exit.

8. You will find the software under "Start Menu->Programs->Philips Online Services SDK->Start

Philips Online Services SDK"


- 9 -

3.3. Usage

Now the software is installed, you can use the SDK to browse your service. The SDK will always require the USB stick to be inserted in the PC.

Never remove the USB stick while the SDK software is running.

3.3.1. First time use

1. Start the software by running "Start Menu->Programs->Philips Online Services SDK->Start Philips Online Services SDK". The following request will appear:

2. Press OK to continue. 3. A full screen window will popup, starting the SDK. If this is not the case, run the SDK again, but this time start "Start Menu->Programs->Philips Online Services SDK->Start Philips Online Services SDK (windowed)". This will start the SDK in a 1280*1024 sized window, so it will also work on screen-resolutions of less than that.


- 10 -

4. After approximately 20 seconds (depending on the speed of the PC on which the SDK was installed) the configuration wizard will run:

5. The configuration wizard consists of a few questions, to make service development easier. All options you select in the wizard can be changed later on. The first screen will request the language for the SDK. Currently, only English is supported as language. The second screen will request the start URL for the browser - the URL the browser navigates to. If you leave this empty, the start URL will be requested each time. The next screen will ask you for an HTTP proxy, if needed on your network. Only non-authenticated proxies are supported (ie. not requiring a username nor password). Do not use "proxy.pac" (ie. automatic proxy configuration scripts) URL's, as these are not supported.

Navigate through the SDK textual menus using Up-arrow,Down-arrow,TAB, Enter or use the numbers in front of the text to select the option. Use space to toggle radio buttons.

6. After the wizard completes, you will find yourself in the main menu:


- 11 -

3.3.2. Main menu

The different menu options of the main menu are:

• Start browser - will request a URL if none is configured, and will start the browser software. The browser screen can look something like this example CE-HTML service :

Important to note is that upon the very first start, the browser is configured for emulation mode. This means it tries to mimick the platform performance to a certain extent. You will notice that your service will load a lot slower than on a regular PC. More on this further on.

• Check for updates - Use this option to check for and install new updates for the SDK. Please make sure any proxy is configured properly which allows HTTP(S) traffic.

• Configuration - this brings you to the configuration menu.

• Exit SDK - this will exit the SDK and will return you to Windows.

3.3.3. Configuration menu

The configuration menu looks like this:

• Network configuration - this should only be used upon explicit recommendation by support. The

system should be configured for DHCP by default.

• Start URL configuration - allows you to edit the start URL. If you leave the start URL empty, the system will request one each time.

• Emulation configuration - this allows you to enable or disable the platform performance mimicking. When you enable it, the performance will be a lot slower, but this is more in line with the actual platform performance you may expect. It is not completely accurate, however, so some things may be quicker or slower on the actual platform. Especially the page loading times will, in the latest version, be slower than on the actual platform, due to network traffic slowdown of the emulation. There is an option here to manually configure the emulation : this should only be done on request of support. For normal development, you can disable the emulation. It is recommended you test your service


- 12 -

with emulation on to verify if your service is usable on the (slower) TV platform. However, no guarantee can be given that if your service works correctly in the SDK, it will work correctly on the platform. This is also due to the fact that the platform has more capabilities than the SDK (e.g. media codecs, input methods etc.). A test on the actual platform will always be necessary.

• Proxy configuration - allows you to setup a proxy server to browse your services with. Only HTTP proxies are supported, without authentication. No automatic proxies, ie. using a "proxy.pac", are supported: you can extract the proxy-url from this file manually.

• Language selection: allows you to select the language in which the interface should be presented. Only English is supported in the alpha-version.

• Return to main menu

3.3.4. Browser

When the browser has been started, the system shows a full-screen browser window with the following characteristics, which also count for the actual platform and your service :

• resolution 1280 X 720 pixels

• 16-bit colors (65536 colors)

• full-screen safe area (meaning the whole screen is available for your service)

• keyboard and mouse support The browser can be controlled using the following keys:

• F1 - help

• Escape - exit browser

• F8 - go back to start url

• Up,down,left,right - navigate through a page

• Enter - OK on an item

• Backspace - Back, navigate a page back in history

• Mouse - navigate through a page A new URL cannot be entered whilst the browser is running, for this you have to exit the browser using the Escape-key and enter a new URL in the Start Browser screen or on the configuration page.

3.3.5. Debugging

To debug your service, you can access the browser's error logs. These will log any javascript errors in your page. To view the error logs, you will have to switch back to Windows using e.g. Alt-Tab. Using a normal browser, e.g. Mozilla Firefox, you can browse to the logfile using the following address: http://127.0.0.1:9180/ (and select the logfile) The logfile is a plain/text document which can be viewed in any text editor, e.g. notepad. For specific service debugging, you can use onscreen printing within the service, for example in a DIV-element:

...

debugdiv.innerHTML="my debug information";

...

<div id="debugdiv" style="left:0px;top:0px;width:100px;height:100px;z-index:99"></div>

For the actual platform, the window.alert method is not supported. For this SDK, the alert messages can be found in a separate logfile.


- 13 -

For mediaobject debugging, this logfile will also contain the methods and properties you call on the mediaobject. E.g. when you send a mediaobject.play(), the logfile will show something like "Mediaobject: play()".

3.3.6. Updating

When a new update is available, and your SDK is properly configured for network access, the system will report a new update automatically. If this is the case, use the "Check for updates" option in the Main Menu to install the updates. It is important that your proxy settings, if needed for your network, are correct. You can verify this by starting the browser with an HTTP and an HTTPS-url. If both URL's load properly in the browser, your network is correctly configured to receive updates. New updates will also be reported on the Wiki, so be sure to peruse that site regularly. If you cannot update your software, let Philips Online Services support know as soon as possible ; some updates are critical for service development. If needed, the USB stick you have can be exchanged with a new one.

3.3.7. Troubleshooting

When you experience problems with running the SDK, please check possible symptoms and solutions below. If these solutions do not solve your issue, post a message on the Wiki support forum and please mail [email protected]. Q: When I start 'Start Philips Online Services SDK' - it briefly gives a black screen, but then does not work ? A: The SDK requires a minimal screen resolution of 1280*1024 pixels. Please run 'Start Philips Online Services SDK (windowed)' to run the SDK in windowed mode. The window size is still 1280*1024 pixels ; you can move the window to center it better. Q: The USB stick is inserted in the system, but the SDK doesn't find a USB stick ? A: Please verify if there is a drive called "Philips UFD" listed in "My computer". If this is not the case, then try reinserting the USB stick in another USB slot. If this does not work, try disconnecting any network drives. Q: When starting the SDK ('Start Philips Online Services SDK'), and after pressing Enter when the request appears to insert the USB stick, the window shows some messages and then closes without starting the SDK. A: This could be a conflict with Cygwin. Please check if Cygwin is installed on the system, and remove or rename the Cygwin directory if this is the case (e.g. "c:\cygwin" to "c:\cygwin_old"). Q: The SDK runs very slow. A: Verify you are running a system that conforms to the minimum system requirements. Try disabling the emulation mode from the "Configuration menu". Q: Upon installing the SDK, my virusscanner reports a problem with 'nsscm.dll'. A: NsScm.dll is part of the NullSoft installer the SDK was built with. One can safely ignore this message. Q: The mediaobject does not work in the SDK, the samples do not give the black rectangle (which represents the video in the SDK) ? A: Omit the data="" tag from the mediaobject <object ....></object> declaration. A: Please make sure your HTTP server submits the mimetype of the video or audio, refer to the SDK guidelines for details. A: When testing, verify that you do not have a proxy server that caches the responses, this could present old testpages to the SDK browser.


- 14 -

4. Developing your service

4.1. Introduction

This chapter will, very briefly, introduce you to the development of a CE-HTML Online Service. It will give you pointers on where to look for more information. It will not give a complete example of an Online Service, nor give you all the details on how to make the best performing and compliant service. Refer to the guidelines documentation for this information.

4.2. Overall

A CE-HTML Online Service for the 2008 TV platform is compliant to the CE-HTML language as specified in the ANSI/CEA-2014 standard, latest revision [1]. Specifically, the TV platform will conform to the so called iBox Remote UI Client specification of the standard. A basic view of CE-HTML in respect to the current web standards is shown in the following image:

A CE-HTML client conforms basically to the following specification:

• ECMA-262 (Ecmascript) [2]

• XHTML 1.0 transitional or strict [3]

• DOM 2 - with support for : o DOM level 2 core [4] o DOM level 2 style [5] o DOM level 2 events [6] o DOM level 2 HTML [7]

• CSS TV Profile 1.0 [8]

• GIF, JPEG and PNG image formats

• Media object (A/V scripting object)

• XMLHttpRequest object

• Notifsocket handler

• 3rd party notifications Note that the last two bullets, i.e. the NotifSocket and 3

rd party notifications are not supported by the current

platform. This is likely to change in future versions of our platform.


- 15 -

The specification can be extended with device-manufacturer specific items such as javascript extensions. These extensions are specific, and are not supported by all CE-HTML clients Some items from the CEA-2014 standard are not relevant cq. not supported for the 2008 version of the TV platform, here is a brief list :

• Support of the AccessKey for standardized key-codes, instead use global keyhandling

• <op> tag for logical key mapping

• Persistent media object

• CSS-3 "image orientation" property

• window.download method

• CE-HTML overlayed on video

• Notifsocket handler

• 3rd party notifications

• No support for window.alert nor window.scroll functions

• CE-HTML capability exchange mechanism

• UPnP integration The browser running on the platform is Opera for Devices 9.5. This is the same browser as is running inside the SDK. For complete and actual information on the capabilities of the platform, refer to the separate Platform Documentation.

4.3. Technical

The remote control keys which are supported for the SDK are as follows, named by their virtual key constants name as defined in CEA-2014, together with their SDK keyboard equivalent :

• VK_UP Up cursorkey

• VK_LEFT Left cursorkey

• VK_RIGHT Right cursorkey

• VK_ENTER Enter cursorkey

• VK_0 .. VK_9 0-9 keys

• VK_PLAY F5 key

• VK_PAUSE F6 key

• VK_STOP F7 key

• VK_BACK_SPACE (VK_BACK) Backspace key This list can be expanded in the future with new keys. In an Online Services page, you can refer to these keys using regular Javascript, e.g.

function keyhandler (e)

{

if (e.keyCode == VK_LEFT)

{

...

}

}

...

Refer to the wiki and/or guidelines and requirements documentation for more information on how to develop your service.


- 16 -

Appendix A - Linux installation There are two installation methods available: binary and from source. The source-based installation is recommended, as this is needed to also compile the KQemu kernel module. The build proces has been tested under Suse 10.0, running under root (for kernel module installation). You will need GCC 3.X to compile Qemu. You will need the same compiler as used for the kernel and root-permissions (e.g. GCC 4.0) to compile and install KQemu. Without KQemu, the SDK will run slower. Source-based installation: Requirements: GCC 3.X, root-permissions on the system, kernel header files (e.g. /usr/src/linux), same compiler as used for Kernel compilation (ref. to `dmesg | head -1`) * run "make.sh" in the top level directory, with as argument the path in which the SDK software should be installed, e.g. "make.sh /usr/local/olssdk" * after compilation, you will find "run_ols_sdk.sh" and "run_ols_sdk_fullscreen.sh" in this installation directory * run one of these scripts as: "run_ols_sdk.sh </path to USB drive>", e.g. "run_ols_sdk.sh /media/PHILIPS_UFD" the run_ols_sdk_fullscreen.sh runs the SDK in full-screen mode. Binary-based installation (without KQemu accelerator): The binary was compiled under Suse 10.0, i586, with GCC 3.4. * copy the directory "binary" over to a local path, e.g. "mkdir /usr/local/olssdk;cp -ar binary/* /usr/local/olssdk" * refer to source-based installation instructions on how to start the run_ols_sdk.sh script. Separate compilation of only KQemu : If you would like to use the binary versions of Qemu, but compile KQemu separately, do the following: Requirements: Root-permissions on the system, kernel header files (e.g. /usr/src/linux), same compiler as used for Kernel compilation (ref. to `dmesg | head -1`) * cd to "kqemu/" in the sourcetree. * "./configure" * "make install" * "modprobe kqemu" to load the kernel module Troubleshooting If errors appear while inserting the module, such as "invalid module format", check if you're GCC and kernel header files are the exact same versions as listed in the `dmesg | head -1` line, e.g. GCC 4.0.

Documents

Philips SDK Manual