shr-project / ffalarms Goto Github PK

Ffalarms
========

Ffalarms is a program to set multiple alarms a day using a finger
friendly user interface (hence the name).

Three clicks to set an alarm time.  Progressive volume.  Snoozed with
double click and turned of with a slider.  LED night clock included.

Ffalarms uses an analog-like clock face to select a time of the alarm
so only one to three clicks are needed to pick a time: one to select
an hour, optional one to select a minute (if not 0), and optional one
to select AM/PM (if not AM).

The alarm starts quietly and slowly increases the volume up to the
maximum.  Thus you may be awaken by a gentle sound if your sleep is
shallow (especially if you select a nice tune as an alarm), but you
may require it to get louder if you are in a deep sleep or hard
working and ignoring distractions from environment.

Ffalarms also contains a 7 segment LED-like night clock.


Author
------

Łukasz Pankowski <[email protected]>


Project home page
-----------------

http://ffalarms.projects.openmoko.org/

The source code is hosted in a git repository at

http://git.shr-project.org/git/?p=ffalarms.git;a=summary


Inspirations
------------

The 7 segment LED-like night clock is inspired by the `LED clock`_
(`on opkg.org`__), which I have discovered on opkg.org_ while having
ffalarms usable on my Neo FreeRuner (though not yet in a releasable
state).

.. _LED clock: http://projects.openmoko.org/projects/ledclock/
.. __: http://www.opkg.org/package_104.html
.. _opkg.org: http://www.opkg.org/


Dependencies
------------

Ffalarms is written in Vala_ (0.7.7 is known to work).

Requires:

- `EFL Vala Bindings`_ (libeflvala) >= r65653
- `libical`_
- atd_ (may be atd-over-fso_ working on top of FSO_ platform)
- ``alsa-utils-amixer`` ``ttf-dejavu-sans``

Optional:

- FSO_ platform (to avoid suspend during alarm by FSO_ platform and
  change backlight brightness in LED clock mode)

.. _Vala: http://live.gnome.org/Vala
.. _EFL Vala Bindings: http://git.freesmartphone.org/?p=libeflvala.git;a=summary
.. _libical: http://freeassociation.sourceforge.net
.. _FSO: http://www.freesmartphone.org/
.. _atd: http://projects.linuxtogo.org/projects/atd/
.. _atd-over-fso: http://projects.openmoko.org/frs/?group_id=260


Suggested media players
-----------------------

``mplayer`` or ``alsa-utils-aplay`` (voc, wav, raw or au only)


Features
--------

- Best works on distributions featuring Elementary_ and FSO_ (such as
  SHR_).  Earlier versions (up to 0.2.2, written in Python) work on
  `Om 2008.12`_ and SHR_.

- Supports recurring alarms.

- Supports snoozing.

- May be configured to use any media player, such as MPlayer_, but
  works out of the box with aplay_ from ``alsa-utils-aplay``.

- LED night clock `12/24 hour mode, brightness and color`_ are
  configurable.

- Adding, listing, and removing alarms is possible from command line
  (see `Command line options`_ below).

- LED clock and analog clock alarm selection are completely themeable,
  as they are implemented in Edje_ using Embryo_ for logic.

- It currently depends on atd_ for alarm scheduling and FSO_ for other
  device interactions such as requesting CPU and Display and setting
  brightness of the LED clock.

.. _Elementary: http://trac.enlightenment.org/e/wiki/Elementary
.. _MPlayer: http://www.mplayerhq.hu/design7/news.html
.. _aplay: http://en.wikipedia.org/wiki/Aplay
.. _Om 2008.12: http://wiki.openmoko.org/wiki/Om_2008.12_Update
.. _Edje: http://wiki.enlightenment.org/index.php/Edje
.. _Embryo: http://wiki.enlightenment.org/index.php/Embryo
.. _SHR: http://wiki.openmoko.org/wiki/SHR


Limitations
-----------

- Ffalarms knows nothing about:

  - Silent profiles: it will play the alarm any way (but on a surplus
    side you can set Silent profile for the night if you wish and it
    will not prevent the alarm to wake you up).

- Ffalarms is currently only configurable through a configuration file
  (see Configuration_ below)

- Currently the list of alarms is not refreshed if the alarms have
  been altered by another instance of ffalarms or the alarm finished.


Configuration
-------------

On `Om 2008.12`_ install ``alsa-utils-aplay`` together with
``ffalarms`` and it should work out of the box.  But if you want to
use other alarm file or player than read on.

The configuration is done through a file ``~/.ffalarmsrc``. If
configuration file does not exist or contains errors (ffalarms will
display proper message) then the default configuration is used which
is equivalent to ::

    [alarm]
    player=aplay -q %(file)s
    file=/usr/share/ffalarms/alarm.wav
    repeat=500
    snooze=5, 60
    volume=60, 100, 105
    alarm_script=/usr/share/ffalarms/alarm.sh

    [ledclock]
    24hr_format=true
    brightness=33

Which will play a given file 500 times (ie. for about 5 minutes).  But
if you have MPlayer_ installed you can use its ``-loop`` option to
obtain the same effect (and then omit repeat as it obviously defaults
to 1) ::

    [alarm]
    player=mplayer -really-quiet -loop 500 %(file)s
    file=~/song.mp3

Reference ``%(file)s`` in the player option will be expanded to a
value of file option with leading tilde (``~``) replaced with the home
directory and proper shell quoting if needed.

The alarm may be snoozed by double clicking the acknowledge window (by
default five times for 60 seconds).

By default volume of the alarm starts at 60 and increases up to 100,
the increase takes 105 seconds.  You can change it by setting
``volume`` to a similar list of three numbers or a fixed volume
(single number).  You can use special value of -1 for ffalarms not to
change the volume.

For example you could use vibrator to play the alarm

  | [alarm]
  | repeat=10
  | player=sh -c 'mdbus -s org.freesmartphone.odeviced /org/freesmartphone/Device/LED/neo1973_vibrator org.freesmartphone.Device.LED.BlinkSeconds 2 100 100; sleep 10'
  | volume=-1

.. _12/24 hour mode, brightness and color:

LED clock by default uses 24 hour format, you can change it to 12 hour
format by setting ``24hr_format`` to ``false``.  You can change the
color by setting ``color`` to ``red, blue, green`` (numbers in range
0-255).  You can also change brightness of the LED clock (which is 33
by default, 100 is the maximum), use special value of -1 to not change
the brightness, for example ::

    [ledclock]
    24hr_format=false
    color = 255, 255, 0
    brightness=-1


Command line options
--------------------

::

    Usage:
      ffalarms [OPTION...]  - finger friendly alarms

    Help Options:
      -?, --help              Show help options

    Application Options:
      -e, --edje=FILE         use Edje interface from FILE
      --at-spool=DIR          use DIR as the at spool directory instead of
      -c, --config=FILE       use config file other than ~/.ffalarmsrc
      -s, --set=HH:MM|now     set alarm at given time
      --summary=STRING        alarm summary (used with --set)
      --del=TIMESTAMP         delete alarm with a given timestamp
      --kill                  kill running alarm
      -l, --list              list scheduled alarms
      --puzzle                show the acknowledge window
      --play-alarm            play alarm
      --version               display version and exit


Credits
-------

Some images are generated from SVG icons from `Tango Desktop Project`_
(licensed under the Creative Commons Attribution Share-Alike license),
this includes ``add.png``, ``remove.png``, ``go-last.png``, and
``led-clock.png`` (generated from ``stock_weather-night-clear.svg``).

Some images are generated from SVG icons available in Debian package
gnome-icon-theme_ (licensed under `GNU GPL v2`_) which says they are
available from here__, this includes go-last.png, gtk-close.png, and
ffalarms.svg (based on appointment-new.svg).

Alarm file ``alarm.wav`` is taken from `Trolltech's Qtopia`_ Open Source
edition version 4.3.2 which is licensed under `GNU GPL v2`_.

.. _Tango Desktop Project: http://tango.freedesktop.org/
.. _gnome-icon-theme: http://packages.debian.org/stable/gnome-icon-theme
.. __: http://ftp.acc.umu.se/pub/GNOME/sources/gnome-icon-theme/
.. _GNU GPL v2: http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
.. _Trolltech's Qtopia: http://qtopia.net/modules/devices/


TODO
----

- Should preserve list selection on list update.

- The list would get more readable if the items would be of the form
  "Today 18:30", "Tomorrow 7:00" in huge letters.  Would require
  responding to change of date at midnight.

- May support "repeat=5m" for playing the alarm for five minutes
  instead of given number of times.

- may add "killing the alarm by accelerators would be an excellent
  option!"  (suggested by Vanous)


Versions
--------

0.4 (2010-03-25)
................

- add snoozing alarm with double click (replaces puzzle)

- only one alarm is playing at a time (new one may start if the
  playing one is stopped or snoozed)

- alarm list now works in single item selection mode, displays alarm
  summary in a separate line and uses simple recurrence rules,
  ex. (daily)

0.3.2 (2010-02-20)
..................

- add editing of recurring alarms

- clicking anywhere inside summary box activates it (closes: #300)

- compiles with current libeflvala (a18c70a, 2010-01-26)

0.3.1 (2009-10-31)
..................

- bug fix: handle empty ~/.ffalarms/alarms file
  (thanks to jeremy jozwik and Vikas Saurabh for discussing the issue
  on the community mailing list)

- add editing of non recurring alarms

- make puzzle digits twice bigger for without glasses readability

0.3 (2009-10-26)
................

- add support for recurring alarms and choosing alarm date from a
  calendar

- add configuration option for volume, alarm_script and alsa_state

0.2.4 (2009-09-19)
..................

- now looks like other Elementary programs

- LED clock: add configuration option to change color of LED digits

0.2.3 (2009-06-28)
..................

- rewritten using Vala/libeflvala/Elementary (same features as 0.2.2)

- avoids suspend and keeps display on during alarm on FSO platform
  (such as SHR)

- note: will not stop alarms added by previous versions of ffalarms

0.2.2 (2009-05-22)
..................

- fix ffalarms not starting due to ecore.evas.engines_get raising
  ValueError instead of returning True (incompatibility between
  python-ecore and ecore; thanks to skamster for reporting)

- add -E, --engine=x11|x11-16 option

- check also for software_16_x11 (new name) apart from software_x11_16
  (old name)

- fix typo in "Scheduled alarms:" on main screen (thanks to Marcel)

0.2.1 (2009-03-27)
..................

- fix to a Daylight Saving Time problem (thanks to Ken Young for
  reporting this)

- disables the screensaver on the phone avoiding it to sleep while the
  alarm is ringing (thanks to Marco Trevisan for the patch)

- analog clock face now shows AM/PM hours or minutes depending on the
  context (thanks to Marco Trevisan for the patch; I reimplemented the
  idea in Embryo)

- now the puzzle is reordered after timeout instead of being hidden

- display error message if unable to trigger atd daemon

- add support for dimming the backlight in Linux 2.6.28 (as in SHR)

- include ``alarm.wav`` from Qtopia (to work out of the box on SHR)

- display error message if there is no atd spool directory instead of
  failing to start GUI

0.2 (2009-02-08)
................

- restore original ALSA state after the alarm (instead of setting stereoout)
- raise puzzle when alarm starts (unless in LED clock mode)
  (thanks to Nathan for the suggestion)
- LED clock: use bigger digits if hour < 20
- LED clock: add configuration option to select 12 or 24 time format
- adding alarm: hours become bigger when clicked for visual feedback

0.1 (2009-01-31)
................

- Initial release