******************************************************************
******************************************************************
Application Description
******************************************************************
******************************************************************
GSMtool dials a number stored in the Pilot's Address Book or
synchronizes the Pilot's Address Book numbers with a
mobile phone.

GSMtool sends and receives SMS messages.

Communication is done via the Pilot's serial interface or
via infrared.

No special protocol is used. The program uses GSM
AT-command extensions. Therefore it is possible, but
not tested that the software runs with other phones
than:
- the Ericsson x888 or any other Ericsson phone
  with attached DI27 or DI28 infrared modem.
- the Siemens S25
- the Nokia 8810 and 7110
- the Motorola timeport

This software is Shareware at $20. Please register at
http://www2.viaweb.com/pilotgearsw/marren.html
Thank you. The evaluation copy runs 30 days. After 20
days, a warning will come up every time you start GSMtool.
After you register, you will get the registered version via e-mail.
German users can register via bank transfer, info on my home page:
http://home.t-online.de/home/Martin.Renschler/GSMtool.html

For support, mail to m.r@mail.com.

No liability for damage. Use at your own risk.

******************************************************************
******************************************************************
System Requirements
******************************************************************
******************************************************************
Palm III with OS upgrade 3.02 and Enhanced Infrared driver, both from
www.3com.com are required or

Palm V with SerIrCommLib.prc and SerialIrPnl.prc, which is part of the
same Enhanced Infrared driver package or

Any Palm with OS 3.3 and Infrared connector.

******************************************************************
******************************************************************
User Guide
******************************************************************
******************************************************************
There is no need to activate the infrared
driver before starting GSMtool in the Pilot's preferences application.

The first time the software starts, it comes up with the preferences
dialog. Later it will always go directly to the dial menu.

******************************************************************
Sync Preferences
******************************************************************
country code
============
If a number either in the mobile or in the Pilot does not start
with + or 00, this string is prepended for the use of
- matching (see if number in mobile is already stored in Pilot)
- dialing
- storing new numbers in either the mobile or in the Pilot
Default is +49 (Germany).

Pilot area code
===============
Same usage as for country code, but used if a number in the Pilot
does not start with +, 0 or 00.
Default is 0241 (Aachen).

Mobile area code
================
Same usage as for country code, but used if a number in the mobile
does not start with +, 0 or 00.
Default is 0172 (Mannesmann D2 operator).

Keep 0 of area code
===================
If the country codes needs to be prepended, then this flag determines if
a leading 0 from the area code is kept. Normally the 0 is removed, but
in Italy the 0 is still part of an international number, e.g.
Rom is +39 06 xxx.
Default is not checked = 0 will be removed.

Position
========
When assembling the name to be stored in the mobile phone, you can choose
the order in which they are concatenated, the maximum number of characters
for this part and the separator between the parts. For example, if you
have a display which displays only the first 9 characters of a phone book
entry (e.g. Ericsson 788 or 768), and you don't care about the title and
you don't care about the company and you don't want any separators between
the parts but you want the Field Code (e.g. M for a mobile phone number)
appended, then the display should look e.g. like this:

1 First name 5
                ___
2 Last name  3
                ___
3 Title      0
                ___
4 Company    0
                ___
5 Field Code 1

The GSMtool program tries first to use your definition. It then calculates the
maximum length that your definition can lead to and compares if the assembled
name has used up the theoretical length. If not, it increases temporary internally
all lengths which are not defined as 0.
If this would lead to an empty entry, e.g. in the example above, if the entry would
contain no first or last name, then, the 0 length definition is no longer regarded,
and those fields are taken into account, too. This is not true for the field code, which
is never included if defined as 0.

Note:
The sum of all field lengths plus the number of separators are internally calculated as the maximum number of characters you want an entry to be in the phone or on the SIM card.
In the example above, it is 9 characters since 5+3+0+0+1 and the separaters are empty.
If you choose this sum to be too high, this may lead to the error:
"ERROR received instead of OK ..." when writing to some phones, e.g. to the
Siemens S25. Other phones may just clip the entry at its end and not throw an error.
There is no golden rule for the length as there are many different SIM cards around.
A reasonable size is 16 characters.
There is an AT command to question the maximum length, but on some phones,
junk is returned, e.g. "8", though they could take 24 characters.
Also, most phones show only part of an entry when looking/scrolling the name list. This
is usually determining the max length you want since otherwise you cannot distinguish
the entries during a search.
Therefore I have decided to let you set the length. Unfortunately, I let you only define one length despite the fact that the phone and the SIM card usually can store different max. lengths. The reason is mentioned already above: The scrolling limitation is the same for both storages.

Field Codes
==================
When the numbers are transferred to the mobile, the names can
get a single capital letter appended which tells you later
from which field of the Pilot address book the number was taken
from (The Field Code). There are 8 letters for the fields in the order:
  work,home,fax,other,email,main,pager,mobile
Default is WHFOEMPM.

******************************************************************
SMS Preferences
******************************************************************
SMS Mail Gateway
Normally, an SMS is sent to another mobile. In this case you
send the number to a mobile phone extension.
But, there are special SMS extension numbers which are not mobile
phones but Gateways. One example is an SMS-to-email gateway.
You send an SMS to the Gateway and the Gateway forwards the
text as an email to the receiver.
To relieve you from the work to insert the Gateway number every
time you want to send an email, GSMtool has coupled the insertion
of the Gateway number to the "Ins E-mail" button press. If
the To: field is still empty, it will insert the number from this
preference. In Germany's D2 net the number is 3400.

Fax Number Prefix
One other way to address a Gateway, e.g. a Fax Gateway, is to
use a special prefix in front of the fax number. 

In Germany's D2 net, this is done by prefixing the number
with a "99". Unfortunately, the "+" sign is not accepted behind this
"99" tag. So what GSMtool does is: remove the "+" of a number if it
finds one and replaces it with 00. The 00 is currently not configurable,
let me know if an option is needed for this. You can still correct the
number before sending the SMS.
(Note: In Germany's D2 net, one Fax costs DM 1.99=$1)

Fax Text Prefix
If there is no number prefix for faxes, the SMS gateway has to know
in another way that the SMS should be sent as a Fax.
In Switzerland, this is done by starting the SMS text content
with *FAX#. You can enter this in this preference field. For Germany
this field stays empty - the tagging is done by a number prefix.

Mail Text Prefix
For some SMS-to-email Gateways, the SMS has to start with a certain
tag. In Switzerland, this is done by starting the SMS text content
with MAIL. You can enter this in this preference field. For Germany
this field stays empty - the tagging is done by a number prefix.

SMS Center
IMPORTANT: You must enter a valid SMS Center address here.
Look in the instructions for your network what it says about
the SMS Center number. Note that you cannot send messages
to mobiles in other networks from all SMS Centers. There
are special SMS Centers for crossing the operators border.
Also, if you are abroad or roaming, it might be necessary
to enter the SMS Center of the host network.
This number is not relevant for Ericsson x888 phones and DI27
adapter. Please set the correct number in your phone.
The SMS Center is preset to the one from Germany's D2 network. You must
change this entry to the SMS center of your network (otherwise, you will
get CMS Error 300 if forbidden by the network, or you will be charged more
for sending the SMS, since the SMS is sent via the foreign D2 SMS center)!

Auto Delete transfered SMS
When you use the mailbox feature, the Pilot will transfer the new SMSs from
the phone into the inbox category of the Memo Pad application. If you want
to remove the SMS messages from the phone automatically after the transfer,
check this option. Some phones reject incoming new SMSs when the phone
buffer is full. If this is the case, the option comes in handy. If your
phone overwrites old SMSs when the buffer is full, you don't have to check this
option.

All SMSs on next Get New Mail
When you use the mailbox feature, the Pilot will only transfer new SMS messages.
If you read the SMS message manually already on the phone, then check this option
to get also old SMS messages. This option will automatically be switched off after the
next Get New Mail call.

Generate Debug Memo
If you run into errors, please activate this check box and repeat the action.
When you leave GSMtool, a debug memo will be generated with the title:
GSMtool Debug <Date> <Time>.
Please sync to the PC and display the memo with the Pilot desktop application,
and copy/paste it into a mail and send it to me.
This option will automatically be switched off after you leave the application.

IrDa connection to phone
This check box should normally be activated. If you have your phone connection
via a direct serial cable, the deactivate this option. Please note, some
people have started to test with the Bosch mobile telephone, I don't think
it works yet. I am waiting for the debug memos.

******************************************************************
Dial
******************************************************************
Please note that you must tap the NUMBER and not the
NAME to copy the number from the lookup list to the dial
field. Tapping the name will bring you to the phone book
application, just for convenience in case you want to edit it.

******************************************************************
Sync Address Book
******************************************************************
Notes:
In Step 1, duplicate entries in the Mobile are detected and
produce a warning message.
In step 3, the names, the numbers and two additional columns are
shown of which the left one is for the SIM card location and the
right one is for the phone book location. If you want a number
to go into the SIM card, tap on the SIM column. The short dial
number is shown with an underline indicating a new entry. Duplicate
entries in the Pilot are shown framed. If you
tap on an existing short dial number, the number disappears,
meaning that it will be deleted in the mobile phone. The two
numbers on the bottom "SIM" and "Phone" tell you how full the
phone book is. The missing number tells you how many numbers
stored in your Pilot are not yet in the mobile phone. A warning
will come up if either phone book is full. Then try the other
column.
Below each of the two columns with the short dial numbers, there
is a button "All" and "0". If you press "0", all numbers in the
currently selected category and column will be marked for deletion
in the mobile phone (short dial number dissappears). If you press
"All", the whole category will be marked for download into the
mobile phone. If the memory/SIM of the mobile phone is full, a warning
will pop up. You can then try the other "All" button for the remaining
ones.
Please note that when you have already added some numbers in
step 3, and then change the preferences on the fly, only
newly added numbers will be affected by the new settings.

If you tap on the name, or, if the name has multiple entries, on
the empty field to the left of the number, you can edit the mobile
phone entry. This can be done for new as well as for existing
entries. If the number is not yet marked to be transfered to the
phone (both columns to the right of the number are empty),
taping on the name does not trigger the edit dialog.

If you tap on the number, you can edit the number similar to above.

******************************************************************
******************************************************************
FAQ
******************************************************************
******************************************************************
The FAQ is available at:
http://home.t-online.de/home/Martin.Renschler/GSMtoolFAQ.html


******************************************************************
******************************************************************
Known Bugs
******************************************************************
******************************************************************
If you have a communication error and then, instead of
aborting the operation within GSMtool, try to run another
application, the Pilot will start to loop running into
the same communication error over and over again which
will need a hard reset. No data will be lost.

Bug in the Ericsson SH888:
If you use my dial feature, the 888 dials correctly, but if you
use the 888's redial feature (pressing twice "yes"), the 888 forgets
to send the "+". So either don't use the redial or change the
"+", before you dial, to the international access number (in
most countries: 00). I will put the international access code
into the preferences in a future version.

The Nokia 8810 can hang after the usage wit GSMtool (needs battery removal).
This is a Nokia bug. I send the correct commands. Hopefully, Nokia
will fix this soon. The newest version is 5.00. I have not checked
if the error is still there.

******************************************************************
******************************************************************
Release notes:
******************************************************************
******************************************************************
Version 1.22 99-11-27
==========================
- PilotGear will now send the registered version automatically to
  the customer after paying.
- bug fix: the debug option was following the IrDA check box and not
  the Generate Debug Memo option, but only if you looked into the
  preferences. Sorry for the confusion.
- added header line with date and time to the debug memo
- more robust communications. I noticed that the Motorola times out
  very quickly on the IrDA interface, if you are e.g. busy going
  through your numbers and tagging them for download. This would
  result in all kinds of errors when continuing.
  Now every time I send a command to the mobile, I check
  if the connection is working. If not, you will get a hint and can
  try as often as you want to get the communication working again,
  e.g. by enabling the IrDA feature again on the mobile.
- A new option in the SMS preferences will allow you to download also
  old SMSs into the Inbox (once if enabled). So far you had to use the
  old SMS Receive all feature and store to the Inbox manually
- exit and reenter application if you toggle IrDA option no longer needed
- added descriptions in the readme file about the new options
- the memory buffer for the debug mode is now only allocated if you enable the
  debug mode

Version 1.21 99-11-22
==========================
- SMS mailbox feature enabled
- Support for Motorola Timeport
- Support for Ericsson R320 and DI28
- support for communication via serial line instead of IrDA
- Entries added to the pilot are now of type "mobile"
- More error checks when writing to Pilot
- Search field starts with capital letter as default
  (matching only start of fields)
- debug memo generated on exit of application if enabled in SMS preferences
- 30 day limit for unregistered version

Version 1.01 99-11-04
==========================
- solved Error #774 problem with some mobile phone models (e.g. S25)

Since 15 users have already registered the software, I felt confident, that more will register and I immediately went out and bought an S25 (costing 
as much as 22 registrations), tracked down the error and fixed it within an hour.
Thanks again to the persons reporting the problem and thanks to those who helped to fix it by registering.

Version 1.00 99-11-01
==========================
- application renamed from DI27 (version 1.62) to GSMtool
- support for Pilot OS 3.3
- the new features (SMS Mailbox) is currently blocked until fully tested.
  Since there were many requests for OS 3.3 support, I released this
  intermediate version on the way to implement all the wishes from the
  DI27 wish list.

==========================================
GSM error codes:
after SMS send:
+CMS Error 300:
Problem in the network, try other operator or change SMS Center.
