$Id: autostart-pys60-scripts.txt,v 1.1 2008/02/27 01:03:28 pmaoki Exp $

    autostarting python scripts on a nokia S60 phone (pys60)

NOTE: this has only been verified on series 60 (S60) 3rd edition FP1
(and in particular on the N95-1 and N95-3).

"autostart" means that the script will be started when the phone is
booted (or rebooted).  

first, some dead-ends.  there are several ways to start applications
without user intervention that are documented on the web, but most
turn out to be unworkable in many cases:
- Recognizer plug-in API
  (http://wiki.forum.nokia.com/index.php/Recognizers)
  - if you want to launch an application based on a file's MIME type,
    you use the C++ "recognizer" API.  it is also invoked on certain
    other events; this squirrelly form of API abuse was the only way
    to autostart apps prior to S60 3rd edition.  unless you want to
    sort out a C++ development environment (not having to do so is
    pretty much the point of using python) this isn't really an
    option.
  - it is also possible to use a canned helper application such as
    EzBoot (www.newlc.com) that does the squirrelly part for you.
    however, EzBoot hasn't been updated since 2005 and doesn't seem to
    work for either python or S60 3rd edition.
- if you want to launch an application based on an incoming message,
  there are several possible options:
  - BIO (Bearer-Independent Object) Control API
    (http://wiki.forum.nokia.com/index.php/BIO_Messaging)
    - can be associated with arbitrary incoming messages (SMS, MMS,
      etc.) but like the recognizer API, only accessible from C++.
  - J2ME Push Registry
    (http://wiki.forum.nokia.com/index.php/PushRegistry)
    - this is obviously only useful if your application is a Java
      midlet.
so, really, none of these will work for python on a current phone.

however, python can take advantage of a feature introduced in S60 3rd
edition (the Startup List Management API) which only requires some
resource files to be added to the installer (SIS).  the Startup List
manager will do all of the work of starting python with the right
arguments.  you just have to generate an appropriate SIS, and there
are already working tools to do that.  in fact, the tools used to
generate the python SIS in the first place know about the Startup List
API as well.

(1) prerequisites:

    - a means of building a SIS file from python source files
      - eg: ensymble 0.24 or later
        (http://www.nbl.fi/~nbl928/ensymble.html)
        - version 0.24 added the necessary --autostart option for its
          py2sis command
        - ensymble requires a working installation of python and
	  openssl on the development host.  however, it only requires
	  these tools (it is a single pure-python script) and these
	  are likely to already exist on any linux box, which makes
	  this more convenient than the other SIS tools.
      - eg: py2sis from PyS60 SDK 1.4.1 or later
        (http://sourceforge.net/projects/pys60/)

    - a means of generating non-self-signed SIS files
      - eg: a free developer certificate (devcert) from symbian signed
        (http://www.symbiansigned.com/)
        - remember that a devcert is only valid for a single device
          (IMEI).
      - eg: a non-free (US$200/year) publisher id from symbian signed
        (http://www.symbiansigned.com/) which is outsourced to tc
        trustcenter in germany
	- a publisher id can be used to generate a devcert that is
          valid for up to 1000 devices (IMEI).

    - PyS60 interpreter and script shell, 1.4.1 or later
      - earlier versions probably work - but only version 1.4.0 or
        later interpreters come pre-signed with the manufacturer
        certificates that allow access to key APIs, so there's no good
        reason to use anything older than that.

(2) one-time tasks
    - install the PyS60 interpreter SIS on the phone
      - VOODOO: install this on the C: drive (phone memory) or else
        autostart may silently fail.  if you have already installed on
        E: (removable flash), you may need to remove and reinstall.
    - create the PyS60 script shell SIS with any needed capabilities
      - strictly speaking, added capabilities are only required if you
        expect to write applications that access stuff like GPS, SMS,
        the file system, etc.
	- in newer versions of ensymble you can use the hex version of
	  the capabilities strings below
      - if you are using a free devcert, remember that the signed
        script shell SIS is only valid on the one associated phone

	  python ensymble.py signsis \
	    --cert=devcert.cer \
	    --privkey=devcert.key \
	    --execaps=LocalServices+Location+NetworkServices+PowerMgmt+ProtServ+ReadUserData+SurroundingsDD+SWEvent+UserEnvironment+WriteUserData+ReadDeviceData+TrustedUI+WriteDeviceData \
	    --dllcaps=LocalServices+Location+NetworkServices+PowerMgmt+ProtServ+ReadUserData+SurroundingsDD+SWEvent+UserEnvironment+WriteUserData+ReadDeviceData+TrustedUI+WriteDeviceData \
	    --verbose \
	    PythonScriptShell_1_4_1_3rdEd_unsigned_freedevcert.SIS \
	    script.sis

    - install the PyS60 script shell SIS on the phone
      - VOODOO: install this on the C: drive (phone memory) or else
        autostart may silently fail.  if you have already installed on
        E: (removable flash), you may need to remove and reinstall.

(3) install your script SIS file
    - create the signed script SIS
      - IMPORTANT: it is documented that you must use a UID in the
        protected range (0x00000000-0x7fffffff)
        - VOODOO: use a UID in the range 0x0....... (protected,
          development) or 0x2....... (protected, deployed)
      - added capabilities are only required if your application
        accesses stuff like GPS, SMS, the file system, etc.
	- in newer versions of ensymble you can use the hex version of
	  the capabilities strings below
      - if you are using a free devcert, remember that the signed
        script SIS is only valid on the one associated phone

	  python ensymble.py py2sis \
	    --uid="0x22222222" \
	    --drive=C \
	    --cert=devcert.cer \
	    --privkey=devcert.key \
	    --caps=LocalServices+Location+NetworkServices+PowerMgmt+ProtServ+ReadUserData+SurroundingsDD+SWEvent+UserEnvironment+WriteUserData+ReadDeviceData+TrustedUI+WriteDeviceData \
	    --autostart \
	    --verbose \
	    test.py \
	    test.sis
	
    - install the SIS file on the phone
      - IMPORTANT (and not voodoo): if you chose not to use
        "--drive=C" switch above, install onto the C: drive (phone
        memory) anyway or autostart will silently fail.  the issue is
        that the Startup List manager only looks for its control files
        in a certain directory on the C: drive, and the SIS-building
        tools assume that if you are installing to a different drive
        (such as E:) then you must want the control files installed to
        that same drive as well.

(4) test
    - verify that the application has been installed (an icon should
      now appear in Applications)
    - reboot the phone
    - NB: the application may not start by the time the main phone UI
      shows up (could take a few seconds, could take a minute).
      depending on what else is autostarting, it may not remain as the
      foreground application, either.  however, this is ok as Symbian
      is multitasking.  you can verify that it is running by (1) going
      into Applications and looking for the little "running" indicator
      on the application's icon (and if you click on the icon it will
      foreground), or (2) invoking the task manager by holding down
      the Applications button and seeing if your application appears
      there (assuming you didn't tell it to "hide" when you were
      building the SIS).
    - NB: if your application doesn't run at least 5 seconds or so,
      Symbian will complain that it was unable to start the
      application.  think about putting in a short "sleep" call if you
      think this will be an issue.