PyS60 Python

Symbian S60 now supports also Python programming. In these pages I'll make available some tools and other programs I've created for S60 Python.

Downloads and prerequisites

The Forum Nokia S60 Python homepage contains binaries, links to documentation, Python discussion board, etc. However, it doesn't have the latest release.
PyS60 has now a homepage at sourceforge which contains the latest release, documentation, and the sources.
Nokia Research Center has a project description for PyS60.

Most likely you'll also want to install Python to your PC as well. I use the official release from http://www.python.org/download/.

The tools I use for communicating between PC and phone use the PySerial package, which encapsulates access for the serial port. I've tested it on Windows, they claim that it also works on Linux, Mac Os, etc.

On Windows PySerial requires win32all extensions. You can test whether you have that by typing import win32com on your Python prompt, if you get ImportError, go to http://sourceforge.net/projects/pywin32/, download, install (now the import should work). If you have installation problems, instructions and FAQ can be found here.

Then you can get PySerial here (test it with import serial as above).

Finally, the distribution file of these tools. See the changelog to find out what changed when.

Tools

The tools provided here mostly concern with Bluetooth (BT) communication between a phone and a PC, as well as shell-types of tools.
Here are the current components:

sync
Tool for synchronizing files between phone and PC over Bluetooth.
Derived from ideas and code of Jukka Laurila's fileserver and Albert Huang's syncandrun.
phcomm
Library that simplifies creating client-server applications between a phone and a PC.
Used by sync
btconsole
        Derived from the btconsole that is part of PyS60 distribution.
        Includes sync() as a built-in function. If you use pyrepl, you'll also get a primitive
        shell with commands such as sync, ls, rm, cd, cat, etc.
filebrowser
Minor modifications to the filebrowser that comes with PyS60 distribution, slightly
better browsing, can delete files, ...
glob, fnmatch
        Standard Python modules that are not part of PyS60 distribution, with slight modifications
        so they work with PyS60.
        Glob allows directory listing with wild cards, fnmatch is used by glob. Used by sync, btconsole.

Setting up Bluetooth

Bluetooth is nice for communicating between the phone and PC. Not only can you use it to edit python files on PC and sync them to the phone (or any other files such as MP3s, etc.), transfer files (log files, photos, etc.) from the phone to your PC, get a console and shell that uses PC display and keyboard but executes on the phone, you can also use phone to control an application running on the PC. However, different Bluetooth HW and drivers behave differently and are often not straightforward to set up.

On my laptop (Windows XP, Wicom BT driver), this is what you need to do.
Open Bluetooth configuration, you can find that from the Control Panel.
Choose Bluetooth Configuration from Control Panel

Choose Bluetooth Configuration from Control Panel

From the Accessibility tab select "Let other Bluetooth devices discover this computer."
Enable other devices to discover the computer

In the Local Services tab add at least two Serial Services that associate a BT serial connection with a COM port. Select Auto Startup. Give them a name that lets you recognize which COM port the service corresponds to.
Add serial ports

If you don't have Wicom drivers (which have worked quite nicely for me), you might find something like this under Control Panel -> Bluetooth Devices. Turn the Discovery on and allow others to connect.
Turn discovery on, allow connections

Then add a couple of incoming serial (COM) ports. As I did this on another laptop, the ports were named automatically (COM5, COM10, etc.).
add incoming COM ports

Getting started with sync

Download the distribution file. Open it with Winzip or tar (tar xvzf pytools.tgz). Move pytools/sync.py to the phone (e.g., right-click it on the file explorer, Send To Bluetooth, select your phone) and install it as script. Move pytools/libs/*.py (at least phcomm, glob, fnmatch) to the phone, install them as libraries. On PC, go to pytools/pcfiles, edit sync.config and set the COM_PORT variable to one of the ports you associated with Bluetooth, and run the sync demon with python syncd.py sync.config from a command line (I use cygwin, but you can also use Dos prompt: Start -> Run -> type cmdand press enter). On the phone start Python, select Run Script, run my/sync.py. Find your PC, select the service that uses the same COM port as your sync demon (if the PC offers only one service, that one is selected automatically). Now the rest of scripts and libraries transfer to the phone. Just to be safe so the new version will be found, close phone Python and restart. Study sync.config and the comments in it to figure out how to modify it to transfer arbitrary files between PC and phone. You can have different config files for different purposes, just give the correct config file as an argument to the sync demon (syncd.py). When you change the config file, don't forget to kill and restart the sync demon for it to take effect.

Bluetooth console

S60Py has built-in support for a BT console. That is, you use the display and keyboard of your PC while the Python interpreter runs on the phone.
Windows comes with Hyperterminal, but that is a horrible tool, I recommend against using that. Based on brief search I found IVT which has worked beautifully for me. Install IVT, start the Telnet version of IVT, choose Serial Transport protocol, select the COM port you've prepared for BT console.
ivt serial, COM port

From the handset, start Python, select Bluetooth console from the Options menu, find your PC, select the port. If you select your PC / port as default, next time you can start faster.
BT console connection works

If everything works OK, you should see something like this. Try typing print 'hello', hit enter. Notice that above the system automatically start pyrepl, which provides better line editing capabilities as in unix readline library, including multi-line editing, emacs key bindings, and command auto-completion (with tab). The pyrepl module is included in the source distribution under the extras directory, you can install that by adding entry
('../../libs/pyrepl', '../libs/pyrepl/*'),
to the SYNC_FROM_PClist in sync.config (don't forget to copy the pyrepl directory to ../libs) and running sync. Alternatively, in the distribution I've included PyreplForSeries60.SIS in the pcfiles directory, just send that to the phone and install.
I've also extended some rudimentary shell capabilities such as cd, ls, cat, rm, etc. There are also other shell tools for PyS60 available here, but I haven't had time to study them yet.

Now you should be all set for Python development. Start sync demon from the PC, keep it listening for a COM port. Start BT console using the second COM port associated with BT. Here's a sample session.

First I created a dummy.py file. Calling sync brought it to the phone. The first time you import the module, then you can interactively call its methods. Then I changed the file on PC, re-sync, but you can't import the same module twice in the same session, you have to reload instead.

Troubleshooting and tips

Python can't find serial though I just installed it?
If you have several Python implementations installed, you may get problems. For example, if you have both the python.org Python, and the cygwin Python, the win32all and PySerial modules will probably install to the python.org Python and be not available in your cygwin Python. The easy solutions include removing cygwin Python or moving your python.org Python earlier in your path.
Python on the phone got stuck.
If you have a phone model that has a movable cover for the MMC card, you're in luck. Just open the cover (don't even remove the MMC card), all open apps should get killed, close the cover. Restart Python and BT console and continue.
Otherwise you may have to reboot the phone.
Can't find the PC services from the phone.
Sometimes using the stored default connection doesn't work. It seems that both the phone and PC cache some information which gets out-of-date.
This is roughly the order in which I try to recover.
1. Don't use the stored default connection, but try searching again for your PC and its services.
2. Kill phone apps (either with MMC cover or reboot phone).
3. Log out of Windows, log in, retry.
4. Reboot Windows.
Clever explanations and fixes on this topic accepted...
I just changed a file, synched, the changes don't take effect!
After the first import, you cannot import a module again, the system notices you already have the module and does nothing. Instead, you have to reload(module). This also applies to sync, btconsole, etc. If you change those, you either should close phone Python and restart, or do what I did in my default.py: after import btconsole I have another line saying reload(btconsole). Or what I did in sync() in btconsole.py: I first check with dir() whether the module has been loaded and then choose reload or import.
System can't find my module (how do those paths work anyway?).
On your BT console, type sys.path. That lists the search paths that Python is using. By default it searches first from the Python installation directory, and then from the /system/libs directories of disks C:, E:, Z: (phone RAM, MMC card, phone ROM). In btconsole.py sync() adds "my" directory to the path in case you put sync.py only there but not to the Python home directory. In general, if you have a module that's only a library (say, phcomm.py), but it to /system/libs (of the disk where you installed Python), if you have a module that can be used directly as a script but can be also a library module to others, you can put it to Python's home (e.g., sync.py), it's in sys.path, import will find it.
BTW, there's bt_console.py in Python home. Ignore (delete!) it, what is being used in the Options menu of S60Py for BT console is /system/libs/btconsole.py (both in the standard installation and with these tools).

Acknowledgements

The following people have contributed ideas or code: Mark Adler, Albert Huang, Jukka Laurila, Larry Rudolph, Jurgen Scheible, Paul Wisner.

You can find the latest version at Kari Pulli's page at http://people.csail.mit.edu/kapu/symbian/python.html.