PUTools: Python Utility Tools for PyS60 Python

Symbian S60 now supports also Python programming. Here you can find a Python interpreter that takes input and shows output on PC, connects over Bluetooth to phone, and executes on the phone. You also get simple shell functionality for the phone (cd, ls, rm, etc.). The tool also allows you to synchronize files both from PC to phone (very useful in application development) and from phone to PC (your images, logfiles from the program you are working on, etc.).

Latest development

PUTools has now been tested on 3rd edition. (Dec 3, 2006).

Downloads and prerequisites

First, you need to get Python for S60. 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.
You also need to have Python on your PC as well. I use the official release from http://www.python.org/download/.
On Windows you will need Win32all package. 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.
Now you are ready to get PySerial, which encapsulates access for the serial port. It's needed for the Bluetooth communication. I've tested it on Windows, they claim that it also works on Linux, Mac Os, etc. (Test it with import serial as above.)
The PC front end GUI uses wxPython, so download and install. Get the latest version. For example Enthought Python distribution has a too old version, that won't work.
Finally, the distribution file of these tools. See the changelog to find out what changed when. The web page for the earlier version is here.

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:

push
Python Utility Shell. It uses PyShell components from wxWindows to create a nice
front end on the PC side for an interpreter running on the phone, communicating over BT.
Has builtin support for synchronizing files between phone and PC, as well as simple shell capabilities (ls, cat, rm, ...).
phcomm
Library that simplifies creating client-server applications between a phone and a PC.
filebrowser
Minor modifications to the filebrowser that comes with PyS60 distribution, slightly
better browsing, can delete files, ...
various additional libraries

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, Widcomm 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. Unselect Secure Connection. Give them a name that lets you recognize which COM port the service corresponds to.
Add serial ports

If you don't have Widcomm 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

The BT connection may require you to pair the PC and phone. On the phone go to Connections -> Bluetooth, there go to Paired Devices, and set up a new pairing to your PC.

Getting started with push (Python Utility Shell)

Download the distribution file.

On PC

Open it with Winzip or tar (tar xvzf pytools.tgz).
With a 2nd edition phone (e.g., 6680)

Move putools/phpush.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 putools/libs/*.py to the phone, install them as libraries.

With a 3rd edition phone (e.g., N93)

Connect your phone to PC, open the Nokia PC Suite -> File Manager.
Create directories on the Memory Card: \Python and \Python\lib.
Copy putools/phpush.py to Python directory and putools/libs/*.py to to Python\lib.

On PC, go to the directory where you unzipped the distribution file, further go to putools/pcfiles, edit sync.config and set the COM_PORT variable to one of the ports you associated with Bluetooth.
Start the Python Utility Shell on the PC (still in putools/pcfiles, type python push from the command line).

(With some drivers, such as Widcomm, it doesn't matter which one you start first, some others like Microsoft require you start the PC application first.)

On the phone

Start Python.
Select Run Script, run phpush.py (it may be in the "my" directory). Select Connect to Other..., Find your PC, select the service that uses the same COM port as in your sync.config (if the PC offers only one service, that one is selected automatically).
Now the push window on PC (see image below) should pop up.
Type sync in that window, then the rest of scripts and libraries transfer to the phone.

Study sync.config and the comments in it to figure out how to modify it to transfer arbitrary files between PC and phone.

Here's what you should see now.
ivt serial, COM port

What can you do?

Python interpreter. push provides a Python interpreter that runs on the phone but takes the input from the PC and echos output on the PC.

File synchronization. push has also integrated file synchronization. In the example above, sync first detected that no files had been edited since last sync. I made a trivial edit to phpush.py one directory level above, the next sync sent it over to the phone. Finally, quit sends a signal to phone to stop phpush.py and also push on the PC side will end. A variant called syncl exists, that also reloads a module if you upload a module that was already imported.

Shell commands. Various shell commands such as cd, ls, rm, etc. exist. To find out which ones, type man, man ls, etc.

Snapshots from your phone screen. Now you can also get snapshots of the phone screen (or image files on the phone) and display them on PC (great for demoing your Python program through a projector attached to the PC). You can even save them on files. Type man snap and man view to find out more, these are interactive shell commands.. You can also instrument your Python program's display routine to send the snapshot automatically to the PC by calling sys.stdout.snap() to get animated PC display. Thanks to Larry Rudolph for suggesting the snapshot functionality. Some sample snapshots below.

Startup file. In the beginning the interpreter runs a startup script if one exist on the phone at C:\startup.py. In this example that file simply contains print 'my startup script'. The distribution includes a sample startup file in putools/other/startup.py.

Application development workflow. When developing a simple application (hello.py), the workflow can be as follows. Create hello.py in the putools directory. (It can really be anywhere on the PC, study putools/pcfiles/sync.config comments for details.) In push, type sync. Test it by run hello.py (or import hello or reload(hello), this is regular Python now, run is just a shortcut for execfile). Edit file on the PC, repeat.

More details about the program

push is a modification of the great PyShell / PyCrust tools that come with wxPython. It does a lot of processing on the PC side (formatting and color coding input and output, for example, as well as good multiline editing. It echoes the stderr and stdout outputs of the Python interpreter back to PC over Bluetooth.

push also supports unicode characters. In the example above the title on the phone is reset, the new string contains unicode characters, and things work just right.

If your program grabs the ownership of stdout/stderr/stdin or wants to create its own code.InteractiveInterpreter, you might want to use btconsole.py that comes with the S60Py distribution (or look here for the earlier version of these tools). btconsole.py is more general, it just echos stdout/stderr/stdin over BT to a terminal, but that is a relatively primitive tool..

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 phpush.py and continue.
Otherwise you may have to reboot the phone.
Can't find the PC services from the phone (BT connection doesn't work though it used to).
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.
It may be that the BT pairing of the phone and PC is broken (this tip from Emily Yan)
1. Remove paired device (Control Panel -> BT Connections)
2. Remove the pairing also from the phone (Connections -> Bluetooth)
3. Redo the pairing (with passwords, etc.)
Also check "My Bluetooth Places" (on desktop) -> "My Device" (on the left panel of file explorer) and check that your BT serial ports don't have a red cross checked on them.
If that doesn't work, you can try
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.
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). If you change push-related files, you probably should close phone Python and restart.
System can't find my module (how do those paths work anyway?).
On push, 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 general, if you have a module that's only a library (say, phcomm.py), put 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, it's in sys.path, import will find it.

Acknowledgements

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

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