PyS60 info: standalone app

Info: How to make a standalone application (using py2sis)

Note: the instructions given here apply currently for making standalone applications only for 2nd edition phones (and earlier)! Instructions for 3rd edition phones will be available later. But the following links might help you further at this point when making sis packages for 3rd ed. phones (I haven't tested them myself though): Nokia wiki or ensymble (by jethro.fn ) or http://www.nbl.fi/~nbl928/py2sisng.html.

A standalone application lets you start your own "python application" directly by clicking on an icon on the desktop on the phone (not having to open the python interpreter, "run script" etc. anymore).

The process to create a standalone app is a bit tricky, but if you have walked once successfully through it, then it is straight forward. I have put here many ready working example files that are downloadable - including icons - so you can see how things should look like at any point, and you can try out stuff with them and modify them.

This page addresses the following questions:

- How to make a simple standalone app out of your python script
- How to make a standalone app including your own icons
- How to make a standalone app that includes the python interpreter, so you can
   distribute your app to people who do not have the python interpreter installed
   previously on their Nokia Series 60 device
- How to make a standalone app that includes other *.SIS files , so you can
   distribute your app as one single file
- A "run" through of the above questions with minimal description

For PC only: (Symbian does not provide SDK's for MAC, so you can not do this on MAC)

First of all you need to have the following software installed installed on your machine:

A. Symbian SDK

B. Python plug-in for the SDK

To get the A. Symbian SDK, go to www.forum.nokia.com/main/0,,034-4,00.html
Choose from the download menu: 2nd Ed, FP2 (146268kB)
This will get you the s60_2nd_fp2_sdk_msb.zip file, unzip it and run the setup.exe file to install the SDK (Which SDK is the correct one depends on your phone model. The one referred to in here is for Nokia 6630).
(Hint: when running Python_for_2ndEd_FP2_SDK.exe make sure that the following data appears in the list where it is told where software components will be installed:
Symbian SDKs for Series 60 EPOCROOT Folder C:\Symbian\8.0a\S60_2nd_FP2 )

After that you need to install B. the Python plugin Python_for_2ndEd_SDK.exe
It is included in the PythonForSeries60_1_2_for_2ndEd_SDK.zip file that you have probably downloaded already when you installed your Python interpreter on the phone.
Run the Python_for_2ndEd_SDK.exe file, it will install among other things also the needed py2sis tool. It creates the following directory where it puts relevant files to: C:\Nokia\Tools\Python_for_Series_60\
(If you encounter problems in installing these software, check some hints below).

NOTE: Now you need to add to your path:
C:\Nokia\Tools\Python_for_Series_60\py2sis
(in windows open control panel -> system -> Advanced tab -> Environment variables -> select PATH from the list -> Edit -> variable value)

Now you are set to create your standalone application (creating a *.sis file).

Here is how you make a simple standalone app - a *.SIS file - out of your python script:

On your PC, create a folder named e.g. myapps (C:\myapps). This is your working directory.
Then save your python script e.g. named test.py which you want to turn into a standalone app inside the C:\myapps folder.

Open a command line terminal e.g. via windows: Start -> Run -> then type in: cmd
(It shows e.g. C:\Documents and Settings\Administrator> )

On the command line terminal go to your working directory, the myapps folder by typing:
cd C:\myapps
( C:\Documents and Settings\Administrator>cd C:\myapps
It should then show: C:\myapps> )

On the command line terminal type the command:
py2sis test.py myfirst.sis --uid=0x0FFFFFFF --appname=myfirst

(C:\myapps>py2sis test.py myfirst.sis --uid=0x0FFFFFFF --appname=myfirst )

What is what?
py2sis - an executable that does the file conversion, the rest are parameters: test.py - src - Source script - your python script
myfirst.sis - the name the resulting SIS file
uid=0x0FFFFFFF - Symbian UID for the app (can be between 0x0FFFFFFF and 0x0FFFFFFF)
appname - Name of your application (to appear when you run your app)

Hint: In case you get an error message like this when you run the above command: ERROR [Errno 2] No such file or directory: 'C:\\myapps\\templates\\pyapp_template.tmp' , then there is a quick way to get round. Copy the folder called templates (and its content) from the directory C:\Nokia\Tools\Python_for_Series_60\py2sis into the directory C:\myapps . Now you should be able to run the py2sis command successfully.

The resulting standalone app file is called myfirst.sis and is found in your C:\myapps folder. You can push this to your phone, install it and run. When running you can see that it uses a standard icon (puzzle image). If you want to have your own icon then go through the next part of text here below.

You can test the making of a standalone app with the commands above by using this example test.py script.
The resulting standalone app file is myfirst.sis.

How to make a standalone app including your own icons:

You can use an own icon for your application. It will show on the top of the canvas (icon1) when running your app (instead of the snake) and also on the desktop of the phone (icon2).

1. Creating the icons

In order to create these icons you can use e.g. a graphic editor like photoshop or fireworks:

icon1 for the top of the canvas (when your app is running):
Create a colour bitmap icon (icon1.bmp) and a one-bit mask (icon1mask.bmp) for it, both 44 x 44 pixels in size, save them to your C:\myapps folder

Downloadable examples: icon1.bmp icon1mask.bmp

icon2 for the desktop:
Create a colour bitmap icon (icon2.bmp) and a one-bit mask (icon2mask.bmp) for it, both 42 x 29 pixels in size, save them also to your C:\myapps folder

Examples: icon2.bmp icon2mask.bmp

Note:
Regarding the one-bit mask: In order to create an icon that has tranparent areas, we need to create a corresponding mask to identify those areas. Such transparent areas need to be coloured white in the mask (e.g. in icon1mask.bmp) and areas that stay visible in the icon shall be coloured black in the mask (e.g. icon1mask.bmp).

2. Merging the icons and its masks into an *.mbm file (MultiBitMap):

As a next step you need to create an mbm file with your created *.bmp files using a tool called bmconv that came with the Symbian SDK intallation. You can do this via the command line terminal. (mbm files (MultiBitMap) are pictures in native Symbian OS format. MBM files can consist of either one or multiple pictures (frames)).

Make sure you have saved all your earlier created *.bmp files to C:\myapps

On the command line terminal go to the myapps directory by typing: cd C:\myapps

On the command line terminal type:
bmconv testapp.mbm /c24icon1.bmp icon1mask.bmp /c24icon2.bmp icon2mask.bmp

Hint: make sure you add /c24 (as 24bit colour picture) in front of the icon file name and leave no space inbetween.

The resulting file is testapp.mbm which is found in your C:\myapps folder.
Example: testapp.mbm

3. Creating an *.aif file (application information file):

Now you need to create an *.aif file (application information file that links your icons to your app) using a tool called aif tool that came with the Symbian SDK intallation.
But in order to do that you need to:

A. first have a *.rss file.
For now you can use this example mobiLen.rss file and modify it - e.g. with notepad - See the modifying instructions in bold here:

//--------------------------------------------------------------------------------
// mobiLen.rss
#include <aiftool.rh>

RESOURCE AIF_DATA
{
caption_list=
{
// Determine the name of your app:
// You need to replace the name mobiLen with the name of your own app
// It determines what name is printed below the icon on the phone
CAPTION { code=ELangEnglish; caption="mobiLen"; },
CAPTION { code=ELangFrench; caption="mobiLen";}
// to work round an AIFTOOL bug, you need to have at least
// one language mentioned here
};

// You need to replace the following app uid with your own applications UID that you plan // to use for your app.
app_uid=0x0FFFFFFF;

// Put here the number of icons (not including the masks), in our case we use 2 icons
num_icons=2;

}
//--------------------------------------------------------------------------------

Note: Do not copy & paste the rss file content from the text above (html), rather download and use this example file here:

Example file: mobiLen.rss

Modify the mobiLen.rss file and save it to your myapps folder.

B. Now finally create the *.aif file

On the command line terminal type:
aiftool mobiLen testapp.mbm

(C:\myapps>aiftool mobiLen testapp.mbm )

You can find your ready mobiLen.aif file in your C:\myapps folder . It contains the icons.

Example of the ready usable file: mobiLen.aif

4. Create a preliminary *.sis file to generate a modifyable *.pkg file

The idea here is that we need a *.pkg (packaging file) to insert some information about the myapp.aif file how it should be packaged.

A. On the command line terminal type:
py2sis test.py myfirst.sis --uid=0x0FFFFFFF --appname=mobiLen --leavetemp

(C:\myapps>py2sis test.py mobiLen.sis --uid=0x0FFFFFFF --appname=mobiLen --leavetemp)

What is what?
py2sis - an executable that does the file conversion, the rest are parameters:
test.py - Source script in this case your python script
mobiLen.sis - the name the resulting SIS file
uid=0x0FFFFFFF - Symbian UID for the app (can be between 0x0FFFFFFF and 0x0FFFFFFF)
appname=mobiLen - this is the name of your application inside the phone. (it also defines paths and filenames inside the *.pkg according to this name)
leavetemp - this leaves a temporary folder called temp in which you find useful files

The resulting file that we need at this point is the mobiLen.pkg file (and not the *.sis file). You find it inside a folder called temp that is left over inside your myapps folder.
Example file (unmodified): mobiLen.pkg

Note: the file name mobiLen.pkg comes from the appname that we used in the previous command. If you use a different appname also the *.pkg will change accordingly as well as the paths inside and filenames of other files etc. !).

B. Modify the mobiLen.pkg file

You can do the editing e.g. with notepad according the instructions here in bold text.

mobiLen.pkg example:
----------------------------------------------------------------------------
;
; Standalone Python for S60 app
;
;Languages
&EN
;
; make sure the UID her as 0x0FFFFFFF is changed according to your own
#{"mobiLen"},(0x0FFFFFFF),1,0,0
;
;Supports Series 60 v 2.0
;
(0x101F7960), 0, 0, 0, {"Series60ProductID"}
;
; Files to install:

"default.py" -"!:\system\apps\mobiLen\default.py"
"mobiLen.app" -"!:\system\apps\mobiLen\mobiLen.app"
"mobiLen.rsc" -"!:\system\apps\mobiLen\mobiLen.rsc"

; Add this line and change the myapp.aif to your *.aif file (at beginning and at the end)
"mobiLen.aif" -"!:\system\apps\mobiLen\mobiLen.aif"
; ---------------------------------------------------------------------------

Note: Do not copy & paste the *.pkg file content from the text above (html), rather download and use this ready modified example file here:
Modified example: mobiLen.pkg

C. Save your modified file as mobiLen.pkg to the temp folder inside your myapps folder.
(make sure the mobiLen.pkg is stored to the temp folder)

D. Copy now your earlier created mobiLen.aif file also to the temp folder inside your myapps folder.
(NOTE: make sure your *.aif file has the same name as the *.pkg file which should be the same name as the "appname" given when you generated the *pkg file in step 4)

5. Create now your final *.sis file by using this time the makesis tool:

A. Go to the temp directory by typing on the command line: cd temp

B. On the command line terminal type:
makesis mobiLen.pkg

(C:\myapps\temp>makesis mobiLen.pkg )

The resulting standalone app file is called mobiLen.sis and is found in your C:\myapps\temp folder. You can push this to your phone, install it and run. It should now have your own icons included.

Final working example: mobiLen.sis

Note: If you want to add also the python interpreter into your sis file, you can go through the detailed instructions below, or take this shortcut: all you need to do is basically copy the python interpreter sis file into you temp direcory and add this line in the mobiLen.pkg file: @".\PythonForSeries60.SIS",(0x10201510) . After that run: makesis mobiLen.pkg

How to make a *.SIS file that includes the python interpreter, so you can distribute your app to people who do not have the python interpreter installed previously on their Nokia Series 60 device:

1. Create a preliminary *.sis file to generate a modifyable *.pkg file

The idea here is that we need a *.pkg (packaging file) to insert some information on how to package the python interpreter into it.

A. On the command line terminal type:
py2sis test.py myfirst.sis --uid=0x0FFFFFFF --appname=mobiLen --leavetemp

(C:\myapps>py2sis test.py mobiLen.sis --uid=0x0FFFFFFF --appname=mobiLen --leavetemp)

Note: the name mobiLen.pkg is because the appname that we used in the previous command was called mobiLen (when you use a different appname also the *.pkg will change accordingly as well as the paths inside and filenames of other files there).

B. Modify the mobiLen.pkg file

You can do the editing e.g. with notepad according the instructions here in bold text.

"default.py" -"!:\system\apps\mobiLen\default.py"
"mobiLen.app" -"!:\system\apps\mobiLen\mobiLen.app"
"mobiLen.rsc" -"!:\system\apps\mobiLen\mobiLen.rsc"

; Add this line here (at the end)
@".\PythonForSeries60.SIS",(0x10201510)
; ---------------------------------------------------------------------------

Note: Do not copy & paste the *.pkg file content from the text above, rather download and use this ready modified example file here:
Modified example: mobiLen_with_interpreter.pkg

C. Save your modified file as mobiLen.pkg to the temp folder inside your myapps folder.
(make sure the mobiLen.pkg is stored to the temp folder)

D. Copy now the python interpreter sis file (pys60 v.1.2\2ndEd) also to the temp folder inside your myapps folder.

E. Create now your final *.sis file by using the makesis tool:

Go to the temp directory by typing on the command line: cd temp

Then on the command line terminal type:
makesis mobiLen.pkg

(C:\myapps\temp>makesis mobiLen.pkg )

The resulting standalone app file is called mobiLen.sis and is found in your C:\myapps\temp folder. You can push this to your phone, install it. It should install both the python interpreter and your own python app.

Final working example that includes the interpreter: mobiLen_w_int.SIS

Note: If you want to include also your own icons into the sis file check the instructions above on how create icons and how to modify your .pkg file.

How to make a *.SIS file that includes other *SIS files , so you can distribute your app as one files in total.

In the same way as you included the python interpreter, you can also include other *.sis files e.g. of python extensions that other people have created.

A. In the .pkg file (see detailed instructions above) add at the end a line:
@".\theadditional.SIS",(UID of additional SIS)

example: @".\PythonForSeries60.SIS",(0x10201510)

Note:
The UID of each of the SIS file that you add needs to be correct. You can find out the UID by opening the .sis file in an HEX-editor. The first 4 HEX strings are it, but in reverse order.

---------------------------------------------------------------------------------------------------------------------

RUN THROUGH:

First of all you need to have the following software installed installed on your machine:

A. Symbian SDK www.forum.nokia.com/main/0,,034-4,00.html
B. Python plug-in for the SDK Python_for_2ndEd_SDK.exe

Here is how you make a simple standalone app - a *.SIS file - out of your python script:

Create a working directoryC:\myapps. Save your python script in it.

On the command line terminal type the command:
py2sis test.py myfirst.sis --uid=0x0FFFFFFF --appname=myfirst

The resulting standalone app file is called myfirst.sis and is found in your C:\myapps folder.

You can test the making of a standalone app with the commands above by using this example test.py script.
The resulting standalone app file is myfirst.sis.

How to make a standalone app including your own icons:

You can use an own icon for your application.

1. Creating the icons

Save them to your C:\myapps folder

Downloadable examples: icon1.bmp icon1mask.bmp

Examples: icon2.bmp icon2mask.bmp

2. Merging the icons and its masks into an *.mbm file (MultiBitMap):

On the command line terminal type:
bmconv testapp.mbm /c24icon1.bmp icon1mask.bmp /c24icon2.bmp icon2mask.bmp

The resulting file is testapp.mbm which is found in your C:\myapps folder.
Example: testapp.mbm

3. Creating an *.aif file (application information file):

A. first have a *.rss file.
For now you can use this example mobiLen.rss file and modify it - e.g. with notepad - See instructiuons inside file
Modify the mobiLen.rss file and save it to your myapps folder.

B. Now finally create the *.aif file

On the command line terminal type:
aiftool mobiLen testapp.mbm

You can find your ready mobiLen.aif file in your C:\myapps folder . It contains the icons.Example of the ready usable file: mobiLen.aif

4. Create a preliminary *.sis file to generate a modifyable *.pkg file

A. On the command line terminal type:
py2sis test.py myfirst.sis --uid=0x0FFFFFFF --appname=mobiLen --leavetemp

The resulting file that we need at this point is the mobiLen.pkg file inside a folder called temp that is left over inside your myapps folder.
Example file (unmodified): mobiLen.pkg

B. Modify the mobiLen.pkg file

You can do the editing e.g. with notepad according the instructions inside the file.
Modified example: mobiLen.pkg

C. Save your modified file as mobiLen.pkg to the temp folder inside your myapps folder.

D. Copy now your earlier created mobiLen.aif file also to the temp folder inside your myapps folder.

5. Create now your final *.sis file by using this time the makesis tool:

A. Go to the temp directory by typing on the command line: cd temp

B. got to tempfile on the command line terminal and type:
makesis mobiLen.pkg

Final working example: mobiLen.sis

How to make a *.SIS file that includes the python interpreter, so you can distribute your app to people who do not have the python interpreter installed previously on their Nokia Series 60 device:

1. Create a preliminary *.sis file to generate a modifyable *.pkg file

A. On the command line terminal type:
py2sis test.py myfirst.sis --uid=0x0FFFFFFF --appname=mobiLen --leavetemp

The resulting file that we need at this point is the mobiLen.pkg file
Example file (unmodified): mobiLen_no_interpreter.pkg

B. Modify the mobiLen.pkg file

You can do the editing e.g. with notepad according the instructions inside the file.
Modified example: mobiLen_with_interpreter.pkg

C. Save your modified file as mobiLen.pkg to the temp folder inside your myapps folder.
(make sure the mobiLen.pkg is stored to the temp folder)

D. Copy now the python interpreter sis file (pys60 v.1.2\2ndEd) also to the temp folder inside your myapps folder.

E. Create now your final *.sis file by using the makesis tool:

Go to temp directory on the command line terminal type:
makesis mobiLen.pkg

Final working example that includes the interpreter: mobiLen_w_int.SIS

How to make a *.SIS file that includes other *SIS files , so you can distribute your app as one files in total.

A. In the .pkg file (see detailed instructions above) add at the end a line:
@".\theadditional.SIS",(UID of additional SIS)

example: @".\PythonForSeries60.SIS",(0x10201510)

Note:
The UID of each of the SIS file that you add needs to be correct. You can find out the UID by opening the .sis file in an HEX-editor. The first 4 HEX strings are it, but in reverse order.

-----------------------------------------------------------------------------------------------------------------

Few helpful links:

http://www.newlc.com/article.php3?id_article=197

http://www.newlc.com/recherche.php3?recherche=create+mbm+

http://www.newlc.com/recherche.php3?recherche=bmconv