Added a README

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..cb8cdc8
--- /dev/null
+++ b/README
@@ -0,0 +1,175 @@
+README for zavai
+
+"zavai" is a word of the Bolognese language which means "useless thing of no
+value". The idea that I'm trying to do what I can with what I have.
+
+It is written with the purpose of working for me; everything else is optional.
+Feature requests for things that I don't need will likely be ignored unless
+of course they come with patches.
+
+Getting it to work:
+
+ * Install dependencies
+
+   apt-get install valac libglib2.0-dev libdbus-glib-1-dev libgee-dev libgtk2.0-dev libwnck-dev
+
+   Optional: apt-get install polygen polygen-data
+
+ * Compile
+
+   ./configure; make
+
+ * Install dbus.d configuration file
+
+   cp conf/zavai.conf /etc/dbus-1/system.d/
+
+ * Copy the .desktop files of the applications you use more often in ~/.zavai
+
+   For example:
+
+   mkdir ~/.zavai
+   cp /usr/share/applications/tangogps.desktop ~/.zavai
+   cp /usr/share/applications/navit.desktop ~/.zavai
+   cp /usr/share/applications/vala-terminal.desktop ~/.zavai
+   cp /usr/share/applications/midori.desktop ~/.zavai
+   cp /usr/share/applications/zhone.desktop ~/.zavai
+   cp /usr/share/applications/FBReader.desktop ~/.zavai
+   cp conf/satmon.desktop ~/.zavai
+
+ * Update the information about the polygen grammars installed in the system
+   (optional) 
+
+   src/update-polygen-info
+
+ * Run zavai
+
+   ./run
+
+   This will run zavai and restart it if it quits/crashes. If you want to
+   restart zavai (for example after you build a new version) just choose
+   debug/quit.
+
+Features / guide
+
+ * Power menu
+
+ Push the power button to get the power menu, with options to
+ suspend/shutdown/reboot, lock the screen and keep the backlight always on
+ (useful if you are using the openmoko as a satellite navigator in the car)
+
+ * Lock screen
+
+ Hold the power button longer to lock / unlock the screen. If the screen is
+ locked you see a lock icon in the traybar.
+
+ A short push of the power button while locked will turn on the backlight for a
+ bit, which is useful if you want to check the map for a moment. Another short
+ push will show the main zavai window, which is useful if you want to see the
+ time. Another short push will hide the main zavai window.
+
+ * Main window
+
+ In the main window you see the time. If your GPS has a fix, the time comes
+ from the GPS.
+
+ In the top left there is a gps icon. Push it to toggle the GPS to be always on
+ (useful to restart tangogps or navit without needing to reacquire a fix).
+
+ In the bottom there is a button to access the main menu.
+
+ * Tray bar
+
+ Zavai shows several tray bar buttons. One kills the current application (or
+ goes back in the menu if the current application is zavai).
+
+ One hides and shows zavai.
+
+ One hides and shows the keyboard.
+ 
+ One shows the status of the battery.
+
+ * The menu
+
+ The menu should be self-explanatory. It has options for simple GPS management
+ tasks, setting an alarm, running applications, a task switcher, and a polygen
+ interface.
+
+ * Alarms
+
+ It is possible to set an alarm, which will be shown in the alarm window. When
+ the alarm expires, the phone wakes up if it is suspended, and zavai does
+ nothing but print an error message on standard error.
+ 
+ When there will be a documented API to turn OFF the vibrator, I'll implement
+ vibration on alarm.  When I'll implement some audio playing infrastructure,
+ I'll implement playing an audio file as well.
+
+ Patches welcome.
+
+Stability / design
+
+ Zavai currently focuses on the interface side, trying to make it easy for me
+ to reach the functions that I need. I try not to focus on hardware details
+ (yet) (when I can), so I build it on the freesmartphone framework, which is
+ unstable, underdocumented and sometimes untested, whose developers so far have
+ never answered my questions and whose API tends to change every now and again.
+
+ This said, I'm surprised it works for me so far.
+
+TODO list / wish list
+
+ * FSO API "documentation":
+ http://git.freesmartphone.org/?p=specs.git;a=blob_plain;f=html/index.html;hb=HEAD
+
+ * Features to add:
+ - "GPS has crashed" button that turns off and on the GPS
+    - After pushing, turn into a "GPS crashed AGAIN" button that turns the GPS
+      off, removes /var/lib/freesmartphone/ogpsd.pickle and then turns it back
+      on again.
+ - icon linking to "current apps" in the main screen
+ - alarm
+    - vibrate at alarm trigger
+    - play sound at alarm trigger
+    - leave expired alarm on screen until acknowledged
+      (alarm status icon that also brings to alarm menu)
+    - remember alarm names (on request, maybe with an add feature) and how
+      often they are triggered, and show them most frequent first
+    - remember unexpired alarms persistently (again, a table in sqlite?) so
+      that they can be reinstated if zavai is restarted
+    - show active alarms and allow to delete them
+ - calendar, just the GTK calendar widget with buttons to go back, forth and
+   current (fill in with opimd if it will make sense)
+    - fill in day info with data coming from the laptop, but just read only,
+      without edit features. Good to check what's on for the day, and notes can
+      be taken with pen and paper for now
+ - GPX status icon (off, waiting for fix, recording)
+ - GPX waypoint using AUX button
+ - GPX + Audio track
+ - track EPV (and similar) in gpx and kill trackpoints with bad accuracy
+ - Audio note
+    - shortcut icon in main screen
+ - Wake up alarm
+ - Toggle wireless
+    - turn on/off chip
+    - start/stop wicd
+    - start/stop wicd-client
+ - Suspend phone if not calling and gps is not on and backlight is not on
+   (maybe with idle notifier?)
+ - Phone from kapula (or just running kapula)
+ - Split polygen applet in a separate app, ran via a .desktop file
+   (faster zavai startup time, can then integrate a browser in the polygen
+    applet, makes more sense altogether)
+ - Is there a way to lock the screen completely turning off the touchscreen, so
+   that interrupts are not even generated?
+
+ * Not quite needed yet:
+ - GPX log with more features (quality, course, speed, ...)
+ - Take a waypoint then show a menu with a timeout
+    - Add a scribbled note
+    - Add an audio note
+    - Add a text note (tickling the text input method thing)
+   If timeout expires, leave the waypoint with the automatic name
+ - restart zavai
+   (also on dbus fuckup)
+   (can be done by just quitting and let the runner script restart it)
+ - get fix events without requesting the GPX resource (and then? gpx log all the time? what for?)

diff --git a/TODO b/TODO
deleted file mode 100644 (file)
index 017dc40..0000000
--- a/TODO
+++ /dev/null
@@ -1,52 +0,0 @@
-20:05 #vala < enrico> Hello. I'd like to read data from /dev/input/eventN, which, in C, requires 
-                      reading a struct input_event from #include <linux/input.h>. What is the canonical 
-                      way in vala to do such things?
-20:17 #vala < mfpuente> enrico, you have to create a vapi file containing constants, enums, structs and 
-                        functions you need to do that, take a look at v4l2.vapi in your vala 
-                        installation or here http://git.gnome.org/cgit/vala/tree/vapi/v4l2.vapi
-20:17 #vala <@zeenix> enrico: write C functions to do that and bind/call that to/from Vala?
-
-FSO API:
- http://git.freesmartphone.org/?p=specs.git;a=blob_plain;f=html/index.html;hb=HEAD
-
-Features to add:
- - icon linking to "current apps" in the main screen
- - alarm
-    - vibrate at alarm trigger
-    - play sound at alarm trigger
-    - leave expired alarm on screen until acknowledged
-      (alarm status icon that also brings to alarm menu)
-    - remember alarm names (on request, maybe with an add feature) and how
-      often they are triggered, and show them most frequent first
-    - remember unexpired alarms persistently (again, a table in sqlite?) so
-      that they can be reinstated if zavai is restarted
-    - show active alarms and allow to delete them
- - GPX status icon (off, waiting for fix, recording)
- - GPX waypoint using AUX button
- - GPX + Audio track
- - Audio note
- - Wake up alarm
- - Toggle wireless
-    - turn on/off chip
-    - start/stop wicd
-    - start/stop wicd-client
- - Suspend phone if not calling and gps is not on and backlight is not on
-   (maybe with idle notifier?)
- - Phone from kapula (or just running kapula)
- - Split polygen applet in a separate app, ran via a .desktop file
-   (faster zavai startup time, can then integrate a browser in the polygen
-    applet, makes more sense altogether)
- - Is there a way to lock the screen completely turning off the touchscreen, so
-   that interrupts are not even generated?
-
-Not quite needed yet:
- - GPX log with more features (quality, course, speed, ...)
- - Take a waypoint then show a menu with a timeout
-    - Add a scribbled note
-    - Add an audio note
-    - Add a text note (tickling the text input method thing)
-   If timeout expires, leave the waypoint with the automatic name
- - restart zavai
-   (also on dbus fuckup)
-   (can be done by just quitting and let the runner script restart it)
- - get fix events without requesting the GPX resource (and then? gpx log all the time? what for?)