NOTE: currently (2006-03-25) this does not work, because yahoo
has changed the weather html structure. will fix when i have time.


dashboard - information pane for s60 phones

author: simo salminen, ssalmine@users.sf.net, ranq @ freenode #pys60

features:
 - weather updates from yahoo 
 - shows upcoming events from calendar and todo entries
 - dashboard can be brought to foreground from phone application soft key

installation:
 First, download and install s60/python 1.2 for 2nd sdk (old phones
 not supported).

 Then, depending on the phone model, do following:
  2nd fp0 or fp1 phone (6600, 7610)
   - go to phone settings->phone->stand by mode->right selection key
   - configure the calculator application
   - then, install 'dashnotify_calc_kludge.sis'. this will override your
     calculator. don't worry, nothing will be overwritten, you can uninstall
     "Dash Notify" and everything will be back to normal.
   - after that, your 'calculator' will actually be 'dash notify' program,
     which is used to bring dashboard to foreground. don't worry about losing
     the calculator, go to http://mtvoid.com/calcium/ and get better one.
     
   
  2nd ed fp2 (6630)
   - install 'dashnotify_2nd_fp2.sis', and then use settings to setup 
     'dash notify' to right soft key.

  After these, you are ready to install the actual dashboard. Install the
  'dashboard.sis'.

 Now, you are ready to start the dashboard. Do that, and wait a bit. After
 the program starts, you have to configure the dashboard. You need to know
 these things:
 - yahoo weather station code
 - internet access point id for automatic connection
 - how often you wish to update weather data

 For the station code, go to http://weather.yahoo.com/. For example,
 "Finland, Tampere" is "FIXX0031" (check the URL).

 Next, press options->list internet APs. Select the one you would normally
 use for internet. It will show dialog with iap number. Select 'weather' 
 and 'configure'. Enter the station and iap number. To the interval section,
 insert how often (in seconds) you wish to update. Please note that it will
 transfer about 2.6 kB for each time. So if you update each hour, it will
 sum up to ~2 MB a month. Be careful.
 
 By the way:
 I TAKE NO RESPONSIBILITY IF THIS PROGRAM CAUSES MASSIVE PHONE BILL FOR YOU.

 Source is provided, so you are free to analyse if running this program is 
 good idea.

 After the 'weather' config, you can configure the 'calendar'. The
 only options the ordering of todo entries. You can have ascending or
 descending order, based on the due date.
 
 After these measures, it is time to restart the dashboard. This is not 
 stricly necessary, but restarting will show us faster if weather updates
 are working. After restart, you should see that the gprs connection is 
 established. Wait a while, then press options->show dashboard. You should
 see nice dashboard.

 Now, press right soft key. After this, press the menu key, and go to 'phone
 application'. Now, press 'Calculator' (or 'Dash Notify' in FP2). It should
 show you the dashboard. Press right soft key to return.

troubleshooting: 

 If you run into problems, create a folder named "debug" inside the
 \system\apps\dashboard\. Then run the program, and email me the
 logfile that is generated inside there.


concepts and implementation techiques:
 - does not perform weather updates when battery low
 - ao_callgate example
 - calendar, to-do access
 - iapsocket - socket module which uses pre-defined internet access point
 - appswitch - enables switching applications foreground/background
 - notifier - this c++ app notifies python process, when user presses
   'phone application' soft key. the dashboard is then brought foreground.
 - cfgform - easy to use configuration with python dicts
 - exttimer - scheduling events beyond 35 min and 47 sec (ao_sleep limit)
 
bugs:
 - the iapconnect bugs when closing down application (KErrNotReady at
   connection.stop())
 - kern-exec 3 when application close (this is s60/python bug with ao_sleep)


version history:

 v.20051023:
  .: initial release

file layout
===========
dashboard.py # our application
dashboard.cfg # our config - list of enabled plugins
plugins\
 <plugin name>\
  plugin.py # main file
  plugin.cfg # plugin specific configuration file

dashboard.cfg format
====================
{'plugins': ['plugindir#1', 'plugindir#2']}
Please note that order is important. The ordering can be
changed from the startup UI.

plugin.cfg format
=================
please see cfgform module doc string


Plugin API
==========

Every plugin must be inside it own subdirectory. Every plugin should
have file plugin.py. This file is loaded by the framework. In this
module, the function init_plugin is called.

Please see example implementation for more details.

See the weather\plugin.py for important details.

Future ideas
============
- rss feed