Bluemote reads the configuration details from a file. It first looks for
~/bluemote/bluemote.cfg file and loads the configuration from that file. If
~/bluemote/bluemote.cfg does not exist, it looks for ./.bluemote.cfg and loads
the configuration from that file. If ~/.bluemote.cfg doesn't exist, it quits
giving an error message.

Description of the config file:
===============================

The config file is of the form:
-------------------------------
[Param List]
<Menu Section>
[Event Section]
[KeyMap]

where,
[Param List]		A list of optional parameters.
<Menu Section>		A mandatory section of the config file that defines
			the menu items to be displayed in the phone and the
			commands to be executed when a menu item is selected.
[Event Section]		An optional section that defines the commands to be
			executed when a particular event occurs.
[KeyMap Section]		An optional section that defines what keyboard keys
			are mapped to the phone keypad keys

Anywhere in the config file, a line starting with a % or a blank line is
ignored. Comments MUST exist on a line of their own. A % symbol in the middle
of a line does NOT cause the program to ignore the rest of the line. A section
starts with the section name within square brackets and ends with "[End]".
Looking at the example config file will help a lot.

Param List:
===========
The [Param List] is a set of lines with a parameter-value pair in each line.
The recognized parameter-value pairs are (case sensitive):

Log		Log I/O and other details. Yes or No. Default: No
Daemon		Mode of operation. Yes or No. Default: No
RetrySecs	Number of seconds between each connection attempt. Default: 60
CharSet		Any character set name that is valid for your phone. T610
		users might be interested in "8859-1". Default: Phone dependant.
GetVol		A command that prints just the volume percentage (no % symbol)
		to stdout. Default: "aumix-minimal -q | grep pcm | awk '{print $3}'"
SetVol		A command that takes the volume percentage (no % symbol) as
		the first argument and sets the volume to it. Default: "aumix-minimal -w"
Device		File name of the device file that represents the rfcomm
		connection to the phone. Default: /dev/rfcomm0

Unrecognized parameter-value pairs are ignored. Examples:
Log No
Daemon Yes
SetVol ~/scripts/set-vol-main
GetVol ~/scripts/get-vol-main

Menu Section:
=============
The <Menu Section> is of the form:
[Menu]
<Menu Item 1>
<Menu Item 2>
..
..
<Menu Item n>
[End]

The [Menu] and [End] strings must appear exactly as "[Menu]" and "[End]". The
symbols [] are not used to indicate optional items in this case.

Menu Item is of the form:
---------------------------
<Menu Text>
<Tab><Menu Command 1>
<Tab><Menu Command 2>
<Tab>..
<Tab>..
<Tab><Menu Command n>

where,
<Menu Text> =	The text that should appear on the Bluemote menu on the phone.
<Tab> =		The tab (i.e \t) character.
<Menu Command> = <Input Command> | <Output Command> | <External Command>
		 | <Internal Functions>

		 <Menu Command>s are executed sequentially till the last
		 command for that menu, or until one of the Input/External
		 (marked with !)/Internal commands/functions return 0 (zero),
		 whichever is earlier. All $variables in a Menu Command are
		 replaced with the value of the $variable before any other
		 processing is done. The replacing is only one level deep -
		 .i.e. If $Text="$Secret", $Text will get replaced by
		 "$Secret" and NOT the value of the $Secret variable.


Input Commands:
---------------

All Input command lines should start with a "<" character. The result of an
Input command will be stored in the $variable of the corresponding name. The
"<" can be followed by (space not necessary) any one of the following commands
(case sensitive) -

Variable	Result(in $variable)	Command Syntax
~~~~~~~		~~~~~~~~~~~~~~~~~~~~	~~~~~~~~~~~~~~
$YesNo		1 - Yes			YesNo <message>
		0 - No
$OnOff		1 - On			OnOff <title> <default Value>
		2 - Off
$Percent	Percent selected by	Percent <no. of divisions> <default division>
		user
$Choice		Choice selected by	Choice <title> <default choice> <choice 1> <choice 2> ... <choice n>
		user (starts from 1)
$Real		Real number input by	Real <title> <prompt> <max real number allowed (inclusive)> [<default real number>]
		user
$Int		Integer number input	Int <title> <prompt> <min (inc.) integer allowed> <max (inc.) integer allowed> [<default integer>]
		by user
$Phone		Phone number entered	Phone <title> <prompt> [<default phone number>]
		by user
$Date		Date entered by user	Date <prompt>

$Text		Text entered by user	Text <title> <prompt> <max length of text allowed> [<default text>]
		after all lines are
		joined to form a
		single long one
$Secret		Secret number entered	Secret <title> <prompt> <max length of secret>
		by user

Examples:
<Text Login "User name" 15
<Secret "Password for" $Text 4
< Choice "Fave Color" 3 Red Blue Green


Output Commands:
----------------
All Output command lines should start with a ">" character. The ">" can be
followed by (space not necessary) any one of the following commands (case
sensitive) -

Command Syntax
~~~~~~~~~~~~~~
<MsgBox> <message> [<timeout>]
<Info> <title> <message>
<Status> <status text>

Examples:
>MsgBox "You have got mail!" 10
>Info "A long line of text"
>Status "Bluemote"

Use MsgBox only when you expect the message to be short. Info is better for
long messages spanning several lines.


External Commands:
------------------
All External command lines should start with a "-" or "+" character. The "-"
or "+" character can optionally be immediately followed by a "!" character.
This is then followed by (space optional) any external program with arguments
for the external program.

Syntax:
<-|+>[!] <external program or script with arguments>

The "-" character indicates that the output of the command need not be stored
in any numeric $variable. The "+" character indicates that the output of the
command must be stored in a numeric $variable. The "!" character denotes,
"stop execution of further Menu Commands if the return code of this command is
0 (zero).

The output of "+" commands are stored in numeric variables $1, $2, .... $n)
when there are "n" "+" external commads in the menu.

Use "+" commands only when absolutely necessary.

Examples:
-xmms &
+echo "Hello"
-! passwdcheck $Secret

Internal Functions:
-------------------
All Internal function lines should start with a ":". The ":" must be
immediately followed by (NO space) any one of the following functions (case
sensitive) -

Function	Description
~~~~~~~~	~~~~~~~~~~~
about()		Display information about the program and author.

tempdisconn()	Disconnect from the phone and wait for 1 minute before
		trying to reconnect to the phone. This will be useful
		if you are connected to Bluemote and would like to
		disconnect and turn off "BlueTooth" on your phone.
		Most phone do not allow you to turn off "BlueTooth"
		when you are connected to Bluemote.

volume()	Control the volume of the computer using the Volume meter
		(percent input command). The feature in this internal function
		that can't be replicated using a script is that volume changes
		not only after "Save" is pressed but also along with changes
		in the meter level

mouse()		Use the joystick and number keys to control the mouse
		on an X server screen. 1 - left button, 2 - middle
		button, 3 - right button, * - double click on left
		button, # - Sticky mode on/off. When in "Sticky" mode,
		the first press of 1/2/3 causes the left/middle/right
		button to be held down till the corresponding key is
		pressed again. Using more than one button in "Sticky"
		mode can be tricky for a new user.

keyboard()	Use the phone keypad to emulate key press on the computer
		keyboard.

refresh()	Reload the config file (searches for the config file
		again, in the usual order).

quit()		Close the connection in a clean manner and quit bluemote.

Examples:
:mouse()
:refresh()


Event Section:
==============

The [Event Section] is syntactically very similar to the <Menu Section>. The
"Menu Text" in the <Menu Section> is equivalent to the "Event Name" in the
[Event Section]. All the command types supported by the <Menu Section> are
supported by the [Event Section], but only "Output" and "External" commands
make sense in most cases.

List of recognized events are:

Event		Description
~~~~~		~~~~~~~~~~~
Connect		When the program connects to the phone in ANY way.
Disconnect	When the program disconnects from the phone in ANY way.
MoveIn		When the program connects to the phone AFTER a disconnect
		caused by the phone moving out of range.
MoveOut		When the program disconnects from the phone when the phone
		moves out of rage.
Ring		When the phone gets a RING signal. The phone gets several RING
		signals for a single incoming call. So execute only
		"idempotent" commands in this event.
IncomingCall	When there is an incoming call.
OutgoingCall	When there is an outgoing call.
CallStart	When an incoming/outgoing call is picked up.
CallEnd		When an incoming/outgoing call is hung up AFTER picking up the
		call.
CallAbort	When an incoming/outgoing call is terminated before someone
		picks up the phone.
Alarm		When the alarm in the phone goes off. Does NOT include
		calendar/task alarms.

The events "IncomingCall" and "OutgoingCall" set the variable $PhoneNumber to
the phone number of the other phone. Unrecognized events are ignored.

Example:
[Event]
IncomingCall
	- echo $PhoneNumber > ~/inlist.txt
[End]

KeyMap Section:
===============
The [KeyMap] is of the form:

[KeyMap]
<Mapping 1>
<Mapping 2>
...
<Mapping n>
[End]

<Mapping> is of the form:
<Keypad> <KeySymbol>

<Keypad> 	The internal string used in the phone to represent a key in
		the phone keypad. 
<KeySymbol> 	A single X-windows key symbol that will be emulated when the
		corresponding <Keypad> is pressed.

Example:
[KeyMap]
2	Up
4	Left
6	Right
8	Down
d	XF86AudioLowerVolume
u	XF86AudioRaiseVolume
[End]
