Deployment on Symbian Devices

This document contains guidelines for deploying the mBS framework along with its basic bundles on a Symbian 7.0 mobile device, such as products compliant with Nokia Series 80 (like Nokia 9500 Communicator) or with UIQ 20 (like Sony Ericsson P800).

You can find useful guidelines in the documents "Target Deployment Guide" and "Platform Deployment Tips".

Basically, you can run an mBS image by simply importing the image files to the target platform by using a PC Suite or a MMC. The image files can be also conveniently packed in a .sis installation file.

Contents:

• Overview
• Series 80
  • Prepare the image
    • Example Directory Structure
    • Example .j9 Launch File
  • Create a .sis file with makesis
    • Use a ready package file
    • Write an own package file
    • Generate the .sis file
  • Transfer the image to the device
    • Directory
    • .sis
  • Launch the image
  • Send commands to the image
• UIQ 20
  • Prepare the image
    • Example Directory Structure
  • Create the image shortcut with AIF Builder
    • Use a ready image shortcut
    • Create an own image shortcut
  • Create a .sis file with makesis
    • Use a ready package file
    • Write an own package file
  • Transfer the image to the device
    • Directory
    • .sis
  • Launch the image
  • Send commands to the image
• Sending commands to the image through link files
  • Link Handler Overview
  • Deploy on the device
  • Install and start the Link Executor bundle on mBS
  • Deploy the native module of the Link Handler
  • Write link files
  • Run link files
• References

Series 80

Prepare the image

For convenience, you can dedicate a directory for modeling the Symbian Series 80 image of mBS. Of course, you can build a Symbian image of mBS straight from its full-content home directory.

Basically, such an image should contain:

• The serverj9.jar or serverj9conn.jar, holding the framework implementation for J9, from the lib installation directory.
• domain.crp, most conveniently placed in the bin/vms image directory.
• A configuration of bundles providing the required functionality. In general, you need at least the OSGi Library Bundle (osgilib.jar) and the ProSyst Util Bundle (putil.jar).

  To avoid additional configuration, you can place the bundles in a bundles directory.

• A .j9 launch file, containing the command arguments to the J9 JVM. This file type is recognized by Series 80 devices as J9 launchable. Suitably, you can place it in a bin/vms/j9 directory.

  As a basis for writing the launch file, you can use the mbs60.j9 script in the bin/vms/j9/sismake_symbian7.0s directory.

• A properties' file or a Config class containing system properties for configuring the image behavior, again in the bin/vms/j9 directory. Some of the properties can be configured in the .j9 file as well.

  You can directly include in the image the jar.prs properties' file from the bin/vms/j9/sismake_symbian7.0s directory.

• A boot INI file loading the bundles from the configuration at the first image startup, or a ready storage. You may include all bundles in the boot INI or in the ready storage to save subsequent bundle installation at runtime since this can be done only in a programming way through the OSGi Framework API.

  For your convenience, the mBS installation contains a ready boot INI installing the base configuration of ProSyst bundles along with the Link Executor bundle for executing commands from link files. The location of the boot INI is bin/vms/j9/sismake_symbian7.0s/boot.ini.

• (Optional) Files to start the image from the Desk
  • An .aif file including label and icon, shown in the application list of the device.
  • An .app file containing C++ code for launching the image .j9 script in a J9 process.
  • A .cfg file containing the path to the .j9 script.
  • A binary .rsc file resulting from a .rss resource file, defining the appearance, behavior and functionality of the image.

  The shortcut files should be in a directory \system\apps\<image_app_name>, e.g. in \system\apps\osgi.

  As generating the files for access from the Desk is not an easy task, there is a ready set of shortcut files in the lib/runtimes/symbian/7.0s/<environment>/system/apps/OSGiServer installation directory. On the device, the shortcut will be called MBS60 and will have the ProSyst icon. By default, the shortcut opens file mbs60.j9 script from the \mbs60\bin\vms\j9 directory. If you want to use your own script, just edit the OSGiServer.cfg file with the right path.

Example Directory Structure

Example .j9 Launch File

Following is an example .j9 file, server.j9, containing most common options for launching the mBS framework. server.j9 assumes that the image is placed within the C:\osgi directory of device.

Create a .sis file with makesis

For convenience, you can create a .sis (Symbian Installation System) file for easy installation of all image components on the device. Here, we'll describe the basic steps to create the image .sis file by using the makesis tool.

To create a .sis file, first you have to create a .pkg package file describing the installation procedure.

Use a ready package file

The Framework Professional Edition Package offers ready-to-use package files placed in the bin/vms/j9/sismake_symbian7.0s directory - fw_template.pkg and fw_emu_template.pkg. The first one is designed for Series 80 physical devices and the second one - for the Series 80 SDK. The resulting .sis file will place the image components in a directory called \mbs60. The image will contain:

• The bundles from the ProSyst base configuration and the Link Executor bundle, all gathered in the bundles directory.
• The mbs60.j9 script, the jar.prs properties' file and the boot.ini boot INI file, placed in the bin/vms/j9 directory.
• The domain.crp file in the bin/vms directory.
• The lib/serverj9.jar JAR file holding the implementation of the OSGi framework for the J9 JVM.
• The components of the Link Handler native module extracted to \system\apps\LinkHandler, \system\recogs and \system\libs.
• The desk MBS6.0 shortcut to the mbs60.j9 script, extracted to \system\apps\OSGiServer.

Write an own package file

You can create your own package file as well - write it by hand or for example use the Sisar tool.

Following is an example .pkg package which contains instruction to take the image files from a certain directory on the development computer and on installation to extract them within the \osgi directory on the user-specified device drive.

Generate the .sis file

With the .pkg file ready, use makesis SDK tool or another utility (e.g. Sisar GUI tool) to create the .sis file from the .pkg one.

Transfer the image to the device

You have several options to transfer the image to the Series 80 device - as a standard directory or as a .sis archive.

Figure 1.1: An example image on a Series 80 device.

Directory

Connect the PC to the communicator over USB, Bluetooth or Infrared. Then, by using the Phone Browser of the Nokia PC Suite copy the image directory, e.g. osgi, to a directory within C:\, e.g. to C:\osgi.

.sis

• From a PC through the Nokia PC Suite - Connect the PC to the communicator over USB, Bluetooth or Infrared. Then, by using the Nokia Application Installer install the .sis file from the PC according to the Nokia PC Suite User's Guide.
• From the communicator device - Do the following:
  • Copy the .sis file from the PC to the file system of the phone by using the Phone Browser of the Nokia PC Suite or by using a Bluetooth or an Infrared connection, etc.
  • Then go to Desk -> Office -> File manager and press Open to start the file manager.
  • In the started file manager, browse to the location of the image .sis file, select the file and press Open. The installation procedure will start.

As a result, the image components will be extracted to the directory on the user-defined drive, as specified in the .sis file.

Launch the image

The image can be started directly by opening a .j9 launch file on the device. In case you have used the shortcut files implemented by ProSyst, you can also use the MBS6.0 shortcut from the Communicator's Desk.

On success, the Communicator will start an application task.

Tip: By default, the Java standard output and error streams are available in the C:\logs\j9vm directory of the Series 80 device.

Figure 1.2: Launching the mBS image on a Series 80 platform.

Send commands to the image

Currently, the Series 80 devices does not have an I/O console in its default set of applications. You can use the Link Handler utility for sending commands to the image. Otherwise, you'll have to develop your own application to command the OSGi framework implementation.

For development purposes, over WLAN you can use a Telnet client to communicate with the mBS image at runtime.

To view the standard output on a remote host, again by using a WLAN you can use also the Remote Console. Currently, due to the constrained Java support on the device, you cannot provide input in this console.

You can also redirect the output to a text file on the local file system.

UIQ 20

Prepare the image

For convenience, you can dedicate a directory for modeling the Symbian UIQ 20 image of mBS. Of course, you can build a Symbian image of mBS straight from its full-content home directory.

Basically, such an image should contain:

• The serverjvm11.jar or serverjvm11conn.jar, holding the framework implementation for PersonalJava JVMs, from the lib installation directory.
• domain.crp, most conveniently placed in the bin/vms image directory
• A configuration of bundles providing the required functionality. In general, you need at least the OSGi Library Bundle (osgilib.jar) and the ProSyst Util Bundle (putil.jar).

  To avoid additional configuration, you can place the bundles in a bundles directory.

• A properties' file or a Config class containing system properties for configuring the image behavior, in a bin/vms/erj directory.

  You can directly include in the image the default.prs properties' file from the bin/vms/pjee31/sismake_symbian7.0 directory.

• A boot INI file loading the bundles from the configuration at the first image startup, or a ready storage. You may include all bundles in the boot INI or in the ready storage to save subsequent bundle installation at runtime since this can be done only in a programming way through the OSGi Framework API.

  For your convenience, the mBS installation contains a ready boot INI installing the base configuration of ProSyst bundles along with the Link Executor bundle for executing commands from link files. The location of the boot INI is bin/vms/pjee31/sismake_symbian7.0/boot.ini.

• (Optional) Files to start the image through the Application Launcher:
  • An .aif file including label and icon, shown in the application list of the device.
  • An .app file containing at least the image application UID.
  • A .txt launch file, containing the command arguments to the UIQ PersonalJava JVM.

  The shortcut files should be in a directory \system\apps\<image_app_name>, e.g. in \system\apps\osgi.

  These UI files can be generated with the AIF Builder tool of the UIQ SDK (see "Create the image shortcut with AIF Builder").

  There is a ready set of launchable application files in the lib/runtimes/symbian/7.0/<environment>/system/apps/OSGiServer installation directory. On the device, the shortcut will be called MBS60 and will have the ProSyst icon. By default, the shortcut opens file OSGiServer.txt launch file for the PersonalJava JVM. You can easily edit the launch file to include custom settings.

Example Directory Structure

Create the image shortcut with AIF Builder

Optionally, you can generate a number of files to make the image startable from the UIQ Application Launcher.

Use a ready image shortcut

The Framework Professional Edition Package offers ready files for image shortcut in the Application Launcher. They are located in the lib/runtimes/symbian/7.0/system/apps/OSGiServer installation directory. The content of the lib/runtimes/symbian/7.0 subdirectory should be copied to the C:\ folder on the device. The ready shortcut expects that the mBS image is placed in the \mbs60 directory of the device.

Create an own image shortcut

You can use the UIQ SDK's AIF Builder to create the set of files needed for displaying the image in the application list (start the builder by using the <uiq_sdk_dir>/epoc32/tools/AIFBuilder script). On successful generation, the tool will create an .aif, an .app and a .txt. The last one contains the command options to the PersonalJava JVM - as a basis for the required command options, you can check the OSGiServer.txt script in the lib/runtimes/symbian/7.0/system/apps/OSGiServer directory. Some of the system properties can be also configured in the .txt launch file.

The .aif and .app files should be placed in a subdirectory of C:\system\apps, specially allocated for the mBS image, for example on the device the .aif and .app files can be placed in C:\system\apps\osgi.

Of course, you can use other tools for generating the set of components for display in the UIQ Application Launcher.

Create a .sis file

For convenience, you can create a .sis (Symbian Installation System) file for easy installation of all image components on the device. Here, we'll describe the basic steps to create the image .sis file by using the makesis tool.

To create a .sis file, first you have to create a .pkg package file describing the installation procedure.

Use a ready package file

The Framework Professional Edition Package offers ready-to-use package files placed in the bin/vms/pjee31/sismake_symbian7.0 directory - fw_template.pkg and fw_emu_template.pkg . The first one is designed for UIQ 20 physical devices and the second one - for the UIQ 20 SDK. The resulting .sis file will place the image components in a directory called \mbs60. The image will contain:

• The bundles from the ProSyst base configuration and the Link Executor bundle, all gathered in the bundles directory.
• The default.prs properties' file and the boot.ini boot INI file, placed in the bin/vms/pjava directory.
• The domain.crp file in the bin/vms directory.
• The lib/serverjvm11.jar JAR file holding the implementation of the OSGi framework for the PersonalJava JVM.
• The components of the Link Handler native module extracted to \system\apps\LinkHandler, \system\recogs and \system\libs .
• The MBS6.0 shortcut extracted to \system\apps\OSGiServer.

Write an own package file

You can write the package file by hand or for example use the Sisar tool.

Following is an example .pkg package which contains instruction to take the image files from a certain directory on the development computer and on installation to extract them within the \osgi directory on the user-specified device drive.

Transfer the image to the device

Similarly to Series 80 platforms, you have several options to transfer the image to the UIQ device - as a standard directory or as a .sis archive.

Figure 2.1: An example image on a UIQ device.

Directory

Connect the PC to the device over USB, Bluetooth or Infrared. Then, by using the File Manager of the PC Suite copy the image directory, e.g. osgi, to a directory within C:\, e.g. to C:\osgi.

.sis

• From a PC through the PC Suite - Connect the PC to the device over USB, Bluetooth or Infrared. Then, by using the Install Software application of the PC Suite locate and install the .sis file from the PC according to the PC Suite User's Guide.
• From the UIQ device - Do the following:
  • Copy the .sis file from the PC to the phone file system by using the File Manager of the PC Suite or by using a Bluetooth or an Infrared connection, etc.
  • Install the file:
    • If the .sis file is in the root directory (C:\), use Applications -> Install, in the displayed list select the mBS image and press Install.
    • In the started file manager, browse to the location of the image .sis file, select the file and press Open.

On success, the image components will be extracted to the directory on the user-defined drive, as specified in the .sis file.

Launch the image

The image can be started directly from the Application Launcher by selecting its icon (set in the .aif file) in the application list. In case you have used the shortcut files implemented by ProSyst, you can also use the MBS6.0 shortcut.

On success, the device will start an application task by passing the arguments from the .txt launch file to the PersonalJava JVM.

Figure 2.2: Launching the mBS image on a UIQ 20 platform.

Tip: As by default, when launched from the application list the Java standard output and error streams are lost, you can use I/O Redirector tool which captures these streams.

For the UIQ 20 SDK only, you can directly call the PersonalJava JVM of the UIQ SDK in the following way:

1. Set the _epoc_drive_j environment variable to <sdk_home_dir>/epoc32/java.
2. Call the pjava or pjava_g executable with proper arguments, as shown for the .txt launch file (Listing 2.1).

Send commands to the image

Currently, the UIQ 20 devices does not have an I/O console in its default set of applications. You can benefit from the Link Handler utility for sending commands to the image by means of link text files. Otherwise, you will have to develop your own application to administer the OSGi framework implementation and the image bundles.

For development purposes, over WLAN you can use a Telnet client to communicate with the mBS image at runtime.

To view the standard output on a remote host, again by using a WLAN you can use also the Remote Console. Currently, due to the constrained Java support on the device, you cannot provide input in this console.

You can also redirect the output to a text file on the local file system.

Sending commands to the image through link files

In some cases, it is not possible to send commands to the mBS framework running on a Symbian device. ProSyst offers a solution to this issue through the Link Handler utility. Next, you can read the command output either from a file or from a remote location.

In general, all you have to do is deploy the Link Handler utility on the OSGi-enabled Symbian device and create text files, which will hold text commands to the framework. The command text files should have the .link extension.

Link Handler Overview

The Link Handler consists of two separate modules - a native Symbian C++ module and an OSGi-compliant bundle with integrated native library.

The native module consists of two C applications - a MIME Recognizer for link files (link files are defined to be of MIME type "prosyst/link") and a handler application, called ProSyst Link Handler, for parsing the content of the .link files and sending the recognized commands to the bundle. In the mBS home directory, the native module comprises the following components:

• For Series 80
  • Wins environment - the lib/runtimes/symbian/7.0s/wins/system/apps/LinkHandler directory, the lib/runtimes/symbian/7.0s/wins/system/libs/mbscmdlib.dll shared library and the lib/runtimes/symbian/7.0s/wins/system/recogs/LINKREC.MDL MIME recognizer application.
  • ARMI environment - the lib/runtimes/symbian/7.0s/armi/system/apps/LinkHandler directory, the lib/runtimes/symbian/7.0s/armi/system/libs/mbscmdlib.dll shared library and the lib/runtimes/symbian/7.0s/armi/system/recogs/LINKREC.MDL MIME recognizer application.
• For UIQ 20
  • Winscw environment, debug variant - the lib/runtimes/symbian/7.0/wins/system/apps/LinkHandler directory, the lib/runtimes/symbian/7.0/wins/system/libs/mbscmdlib_g.dll shared library and the lib/runtimes/symbian/7.0/wins/system/recogs/LINKREC.MDL MIME recognizer application.
  • ARMI environment - the lib/runtimes/symbian/7.0/armi/system/apps/LinkHandler directory, the lib/runtimes/symbian/7.0/armi/system/libs/mbscmdlib.dll shared library and the lib/runtimes/symbian/7.0/armi/system/recogs/LINKREC.MDL MIME recognizer application.

The bundle participating in the Link Handler utility is called Link Executor and its JAR file is linkexec.jar from the bundles mBS directory. When activated on the framework, the bundle starts a command server for executing commands, received on native level from the Link Handler native module.

Deploy on the device

Install and start the Link Executor bundle on mBS

This can be done by including the linkexec.jar in the Symbian image as described in the preceding paragraphs. In a few words:

1. Include the bundle JAR file in the boot INI file so that it is started at mBS startup.
2. Include the bundle JAR file in the bundles directory of the image.
3. (Optional) Build the image .sis file on the development PC.
4. Transfer the image to the device either by directly copying the image content from your PC to the device, or by installing the image .sis file if available.

Deploy the native module of the Link Handler

The components of the native module (see the "Link Handler Overview" section) of the mBS installation should be copied on the device with the lib/runtimes/symbian/7.0*/<environment> directory mapped to the root folder of the device. For example, lib/runtimes/symbian/7.0*/armi/system/libs/mbscmdlib.dll on the PC should be copied to \system\libs\mbscmdlib.dll on the device.

You can do the file transfer manually or include the native module's directories and files in the .sis file.

Note: When reinstalling the Link Handler native module on an emulator (i.e. an SDK), especially when using a .sis file, after the uninstallation stop the emulator and delete the LINKREC.MDL file from the \system\recogs folder. Otherwise, during the re-installation, the emulator will deny access to the system.

Write link files

Link files have extension .link and should be placed in the local file system of the Symbian device. One link file can contain only exactly one command to mBS.

The first line of the link file should contain the special header "prosyst/link" and the second one - the command which the local mBS will execute. For example:

prosyst/link
config.setvalue mbs.log.pid filelength 64

Run link files

1. Start mBS with the Link Executor bundle active. In this way, the command server will start listening for commands.
2. Start the device file manager and open the target link file. As a result, the Symbian OS will call the native Link Handler module, which will check the file and will retrieve the command there.
3. Check the output for the result of the command execution.

References

• Symbian Community Pages
• Nokia Forum
• UIQ Technology Home Page

Deployment