PyS60 1.4.5 Quick Start

From Symbian Developer Community

This Quick Start document provides information on how to begin developing Python applications for the Symbian platform. At the end of the tutorial you will have installed Python (PyS60 v1.4.5) on your phone or Emulator, written a basic helloworld application and run it on the phone both from the interactive shell script and as a stand-alone application.

If you are completely new to Python we recommend you start your development on the desktop - by taking the short course Dive Into Python or working through the tutorial: Python Programming for the Non Programmer.

Contents 1 Setting Up Your Development Environment 1.1 Getting PyS60 1.2 Installing Python on your Phone 1.3 Setting up your Windows PC 2 Your first script 3 Making a Standalone Application 4 Summary 5 Related Information

Setting Up Your Development Environment

Python applications ("scripts") are simply text files containing code written in the Python programming language and named with the file extension ".py". The scripts can be written in any text editor and can be run either from within the Python Interactive Shell application on a mobile device or the Symbian platform emulator, or as standalone applications on your mobile device.

Getting PyS60

The PyS60 1.4.5 (stable release) files are stored at sourceforge.net/projects/pys60. There are different files for the different versions of S60 (descriptions are provided for all files in the Python Technical Overview)

For this tutorial we assume you are working on Symbian platform phones and SDKs. Therefore the files you need are:

• PythonForS60_1_4_5_3rdEd.sis - the Python runtime
• PythonScriptShell_1_4_5_3rdEd.SIS - the Python script shell
• PythonForS60_1_4_5_SDK_3rdEdFP1.zip - the PyS60 SDK
• PythonForS60_1_4_5_doc.pdf - the relevant PyS60 library reference and API documentation (applies to all)

Installing Python on your Phone

The SIS file listed above are compatible with Symbian platform (and any S60 3^rd Edition phones (or later)). If you have a S60 2^nd Edition phone then you will need to download some new files.

Using your PC Suite software, install the following files to your Symbian platform or S60 3rd Edition phone:

• PythonForS60_1_4_5_3rdEd.sis - the Python runtime
• PythonScriptShell_1_4_5_3rdEd.SIS - the Python script shell

You can verify the installation by launching the "Python" icon from the device Installations folder. If you do menu "Options | Run Script", you can select some pre installed scripts to demonstrate the power of Python! The icon and list of applications are shown below:

Figure 1 Python on the S60 emulator

Figure 2 A list of Python scripts

Setting up your Windows PC

Install/unzip/copy the following files (in order):

• Symbian^1 Application Development Kit
  • Note that you'll first need to unzip the SDK to a temporary directory, and then run setup.exe. The patch will then need to be unzipped over the SDK, so that it overwrites the SDK's \epoc32\ directory. Accept all prompts during unzipping to allow this to happen.
  • On first use, the SDK will prompt you to register it. The process is straight forward, but you will need to sign up with Forum Nokia if you haven't already.
  • You can launch the Emulator by clicking on the file [SDK]/epoc32/release/winscw/udeb/epoc.exe. You then navigate to the Python icon in the Emulator in the same way as you did on the device.
• PythonForS60_1_4_5_SDK_3rdEdFP1.zip - The PyS60 SDK
  • The PyS60 SDK ZIP file contains another file named sdk_files.zip. Extract that in the S60 SDK folder (by default C:\S60\devices\S60_3rd_FP2_SDK for the SDK we are using). PyS60 is now installed on your emulator.
• PythonForS60_1_4_5_doc.pdf - Copy of the relevant PyS60 library reference and API docs (applies to all)
• Python 2.2.2 for Windows (needed to run Ensymble to create standalone applications

You will also need a text editor for writing your scripts. We recommend a syntax-aware editor like Notepad ++ but you can use any one you like, including Windows Notepad.

Your first script

The very simple script below asks the user for their name, then displays a dialog with the text: "Hello Name, welcome to Python World."

 
# import the app user interface framework module
import appuifw
 
# create a single-field dialog (text input field): appuifw.query(label, type)
data = appuifw.query(u"Type your name", "text")
 
# create an information note: appuifw.note(label, type)
appuifw.note(u"Hello "+str(data)+", welcome to Python World", "info")
 

Copy this text into your preferred text editor and then save the file as Helloworld.py (the ".py" extension is used for uncompiled python scripts).

If you're using the interactive shell for testing, you need to copy the file to \Python\ on any drive. For the device you can copy the file directly into the correct folder using PC Suite, or send it as a message with Bluetooth and then move it to the correct folder, using a file manager application (YBrowser - recommended). If you're using the emulator you can copy it direct into the appropriate folder - [SDK]\epoc32\winscw\c\python.

You can then test your script in the same way you verified the Python installation - by launching the "Python" icon for the interactive shell, then doing "Options | Run Script" and selecting it from the list.

That's it. You now have Python on your device and/or your Emulator and know how to write/launch scripts. The next section shows how you can package your script as an application.

Making a Standalone Application

Scripts are ideal for testing because they can be quickly and easily modified. However, an application should be distributed in the form of an installable SIS file. This applies even more when the application has external resource files that have to be distributed with it.

The PyS60 1.4.5 tool for creating standalone application's is Ensymble. This is a Python application, so you need to install Python 2.2.2 before it can be run.

Before using Ensymble, we recommend you first read the (very extensive) Ensymble’s readme file. You can then package the script we created in the previous section.

1. Open the Windows command prompt.
2. Navigate to the folder containing your application script and Ensymble script.
3. Type the following command and press Enter.

 
ensymble.py py2sis helloworld.py
 

A SIS file named helloworld_v1_0_0.sis will be created in the same folder. Instructions for using Ensymble on Linux OS are available here.

Many other useful parameters are available for the py2sis command for additional options. Ensymble’s readme file contains more information.

 
--uid=0x01234567
--appname=AppName
--version=1.0.0
--lang=EN,...
--icon=icon.svg
--shortcaption="App. Name"
--caption="Application Name"
--drive=C
--textfile=mytext.txt
--cert=mycert.cer
--privkey=mykey.key
--passphrase=12345
--caps=Cap1+Cap2+...
--vendor="Vendor Name"
--autostart
--encoding=terminal,filesystem
--verbose
 

You might want to compile the Python scripts (PY) to Python compiled scripts (PYC) using Python for PC (python.org) before packaging them in SIS files. Converting to PYC increases performance and execution speed and protects the source code to some extent. The following code commands are used on Python on PC for cross compiling scripts, as shown in Figure 5.

 
import py_compile
 
py_compile.compile('myscript.py')
 
#Compiles myscript.py
 

or

 
import compileall
 
compileall.compile_dir('Myfolder', force=1)
 
#Compiles all scripts in the directory Myfolder
 

Summary

This Quick Start tutorial has shown you how to get set up with PyS60 1.4.5 on the Symbian platform, from getting the developer environment through to making standalone applications.

Related Information

There are plenty of public domain resources to help you get started on learning generic Python, and the PyS60 flavour in particular:

• Python in a Nutshell
• Python Technical Overview
• Dive Into Python - Free book on (Generic) Python programming
• Forum Nokia's Python Elearning Module
• Forum Nokia's Official Python Training course with worked examples
• Applications on Croozeus.com blogs
• Croozeus.com Tutorials
• Mobilenin Tutorials.
• Python reference library (including the modules for PyS60) installed as part of your windows setup.
• Python 2.2.2 Reference
• Mobile Python - Rapid prototyping of applications on the mobile platform by Jürgen Scheible and Ville Tuulos. Symbian Press provides a sample introductory chapter online and a website with source code for all the examples in the book: www.mobilenin.com/mobilepythonbook/examples.html

Sign in to comment…