                              - G N O K I I -
             (C) 1999, 2000, 2001 Hugh Blemings & Pavel Janík ml.
                            (C) 2001 Pawe³ Kot
                  Last update 13 Feb 2002    Version 0.3.4

- Contents - 			   

1.0   Introduction
2.0   About the applications
3.0   Notes for specific model phones
4.0   Installation from source 
5.0   Installation of pre-built binaries
6.0   Configuration
7.0   Known Bugs
8.0   Gnokii and Perl
9.0   How to help
10.0  gnokii by CVS
11.0  Protocol Details
12.0  References
13.0  Handsets/Networks tested
14.0  Credits
15.0  Release Notes

			   
- 1.0 Introduction -

This is version 0.3.4 of gnokii, a Linux/Unix tool suite and modem
driver for Nokia mobile phones, released under the GPL.  Please
see COPYING for more details on license/copying issues, the lack of
warranty and where to send a postcard if you like gnokii :).  This
release provides the much awaited ability to place data calls for
all platforms except Win32.  Fax calls are not supported.

gnokii supports most phones from the 3810/8110, 5110/6110, and 2110
series, details including bugs specific to each series appear in the
files README-3810, README-6110 and README-2110 respectively.  

In the early stages of the project there were indications that
Nokia would provide some support for the project.  Regrettably, these
negotiations stalled over the issue of binary versus open source
releases and the project has proceeded without official or unofficial
assistance.

We have a web site at http://gnokii.org which amongst other things
gives information on how to join the gnokii mailing list, retrieving
bleeding edge releases through CVS and more!

If you haven't already done so, please indicate your interest in 
the gnokii project by adding yourself to the user database
at http://gnokii.org/users


- 2.0 About the applications -
  
gnokii now consists of three main executables and a fourth "helper"
application that is run suid root.  To get the most from gnokii it
is worth understanding the details of them and how they interact.
It is important to note that at present you cannot run more than
one of gnokii, xgnokii or gnokiid at a time.

The first application, gnokii, is a command line utility that was
originally provided to assist developers and interested users in
working with the low level API functions that were being developed.

From these rather humble beginnings, it has evolved into a the main
command line tool of the suite.  Many people now use it for
reading/writing phone book entries, sending and receiving SMS messages
etc.  Ultimately it is intended that it will become a utility that
communicates with gnokiid to provide a command line interface to
the functionality provided by the gnokiid daemon.

The second application provided is xgnokii which as the name suggests
is a X-windows based application that provides a graphical interface
to your phone.  Amongst other things, xgnokii allows you to read and
write phone book entries, read, write and send SMS messages, monitor
battery and received signal strength.

At present xgnokii works directly with the phone, however in the
future it will more likely use the "side" interface of gnokiid.

The third part of the suite is gnokiid.  gnokiid provides a
virtual modem interface, /dev/gnokii that looks like a regular
Hayes-AT compatible modem with the ETSI defined extensions for
GSM phones.  What this means in practical terms is that you can
treat the /dev/gnokii device like an ordinary modem and use it
to make data calls from pppd or a terminal application like
minicom.

gnokiid is still under development, it's ultimate aim being to
act as a "master" daemon that interfaces with your phone on one
side and gnokii or xgnokii on the other.  This "side" code is still
under discussion, particularly with respect to the most appropriate
choice of communication method (IPC, TCP/IP etc.)

The last application provided with the suite is mgnokiidev which is
used by gnokiid to create on demand a symbolic link between
/dev/gnokii and the pseudo tty used by gnokiid for the virtual
modem interface.  It's operation is transparent under normal
usage as gnokiid takes care of calling it when required.

You should be aware of a minor security hole in mgnokiidev -
members of the 'gnokii' group may be able to use it as a way
to access pseudottys in use by other users on the system.  If
you are the only user on your system, or you trust anyone that
you put into group gnokii you have no problem.  If this isn't 
the case contact one of the authors who will try and suggest
a workaround.  It is expected that this problem will be fixed
in the next release of gnokii.


- 3.0  Notes for specific model phones -
  
Please see the README-3810 file for notes specific to the
3810/8110 series, README-6110 for notes on the 5110/6110
series and README-2110 for notes on 2110 series.


- 4.0 Installation from source -

gnokii makes use of autoconf/automake which allows you to configure
the source tree for your system by typing 

./configure

You can also run configure with the --help flag to get a list of 
available options.  There are about a dozen or so that are specific
to gnokii.

Once you've run ./configure successfully, you should be able to
simply do a make and make install to compile and install your 
binaries respectively.

make

make install

With this done you've built and installed your binaries, and
should proceed to the configuration section below.


- 5.0 Installation of pre-built binaries -
  
If you downloaded gnokii as a pre-built binary you should install
it in the conventional manner for the package type in question.
For example if you downloaded a .rpm file you can install it by
running the following as root.

rpm -i gnokii-0.3.4-i386.rpm

If you are using a Debian based system, you can use dpackage
to do the installation. On Slackware you use installpkg or pkgtool.


- 6.0 Configuration -

Once you have installed the binaries, you should copy the
sample/gnokiirc file from the Docs directory to your home
directory and name it .gnokiirc  Using your favorite editor
ensure that the settings are correct for your system, the sample
file has details of the various options available.

If you used a pre-built version of gnokii (.rpm, .deb etc) it
may have installed a /etc/gnokiirc file.  If it has, the 
settings in this file will be used in the absence of a
.gnokiirc file in your home directory.

Note that you will need read/write permissions on whatever
serial port you specify in .gnokiirc.  You can now use gnokii
and xgnokii.

Review the notes specific to your model of phone in either
README-6110 or README-3810 as appropriate.  These files
also provide information about what functionality is
available for each model.

In order to make use of the AT emulator provided by gnokiid
through /dev/gnokii, you must read the documentation file
DataCalls-QuickStart.
 
A simple test to confirm that your cable/IR link is working
is to run gnokii with the --monitor flag e.g.

  foobar$ gnokii --monitor
  
This will attempt to connect to your phone and display
information such as signal strength, battery level  etc.
      
If you get an error along the lines of
	
  Hmmm... GSM_LinkOK never went true. Quitting.
	    
this indicates that gnokii could not communicate with your phone
for some reason and you will need to do some troubleshooting.
		                        

- 7.0 Known Bugs -

Review the bugs section in the README for your series of phone.

Note the possible security hole in mgnokiidev discussed above.


- 8.0 Gnokii and Perl -

There is a perlmodule available for gnokii. It gives access to all
the routines that are defined in gsm-common.h from a perl-program. It
is intended for application developers who want to use their favorite
language in interfacing the phone data with databases, ldap-directories
and (in the future) different calendar applications. It is written by
Konstantin Agouros (konstantin@agouros.de) and support starts with
revision 0.2.6-pre3 of gnokii.

The homepage of this module is http://www.agouros.de/gnokii


- 9.0 How to help -

There are a number of ways you can help out.

Code specific to each model is contained within fbus-3810.[ch] and
fbus-6110.[ch] and other [fm]bus-*.[ch] files. All command handlers
will dump information to stderr when they encounter a message they don't
understand.  If this happens to you, try and work out what is going on.

Suggestions on changes to the code are welcome, the preference is that
they be aired on the mailing list so that a consensus can be reached
when appropriate.  This is particularly important if you intend making
large changes and/or submitting big patches.

- 10.0 gnokii by CVS -

The gnokii project has a new CVS server thanks to Andrew Tridgell
and the Samba team.  The server's address is pserver.samba.org.  If you
are already familiar with CVS, set the CVSROOT to 

	:pserver:cvs@pserver.samba.org:/cvsroot

and use the password cvs for checking out the repository with the name
gnokii.

If you are not familiar with cvs, don't worry. It's very simple.
Just install the cvs package for your distribution and follow these steps:

	1. set your environmental variable CVSROOT. If you have bash (Bourne
           Again Shell):

	export CVSROOT=:pserver:cvs@pserver.samba.org:/cvsroot

	   If you have different shell, use different command (e.g. setenv).


	2. Log in to the CVS server as anonymous reader by typing

	cvs login

	   Use 'cvs' as your password.


	3. If you are logged in you are ready to checkout the latest sources:

	cvs co gnokii

If you prefer, there is a WWW interface to the CVS server at

http://pserver.samba.org/cgi-bin/cvsweb/gnokii/

Once you have the sources, you will need to run the following commands

	autoconf
	./configure
	make

to build the sources.

Now you are on your own - you have the current sources on your disk
in the directory gnokii.  If you are going to make substantial changes
and feel that they should be included into gnokii please mention it
on the list first to avoid duplicated effort.
	
If you would like to receive email when updates are made to the CVS
repository, just send Hugh and email to that effect (hugh@blemings.org)
and you'll be added to the recipients list.

Our thanks go to the Czech Linux Users Group for hosting the original
CVS repository at cvs.linux.cz.

- 11.0 Protocol Details -

3810 Series

The protocol used between the phone and the PC has been worked out
by a mixture of trial and error, monitoring the data that goes between
the 3810 and its Windows 95 software and a few snippets of information
found on the 'net relating to older Nokia models.  Feedback from
people who played with the first release of gnokii was invaluable.


6110 Series

The same applies for 6110 Series (but I use Windows NT 4.0 for
monitoring). The protocol of 6110 Series is somewhat different from 3810
Series. Perhaps the first draft of the protocol for communication between
Nokia mobile phones and PCs was not so general to support the newest features
of Nokia's phones.

You'll find the detailed protocol description in Docs/protocol directory/

- 12.0 References -

The web site for this project is at;

	http://gnokii.org

The mailing list devoted to the gnokii project is

	<gnokii@net.lut.ac.uk>

You can subscribe by sending an email to

	<gnokii-request@net.lut.ac.uk>

with the word subscribe in the body.

The serial programming how-to was valuable in cobbling together
serial code for both monitoring and the tools themselves.  This
is the Australian mirror, there will be one nearby to you too :)

<http://www.monash.edu.au/mirror/ldp/HOWTO/Serial-Programming-HOWTO.html>


- 13.0 Handsets/Networks tested -

3810 Series

3110/Sonera (Finland)
3110/Telefonica (Spain)
3810/Telstra (Australia)
3810/Optus [Actually Hutchison] (Australia)
3810/Mobile One (Singapore)
3810/SingTel Mobile (Singapore)
8110/Proximus (Belgium)
8110/D2 Privat (Germany)
8110i/MTN (South Africa)
8110/Beeline Vympelkom (Russia)
8110i/A1 Mobilkom (Austria)

6110 Series

6190/Microcel (Canada) (GSM 1900)
6150/Viag Interkom (Germany) (GSM 1800)
6150/Omnitel (Italy)
6150/Beeline (Vympelkom) (Moscow, Russia)
6150/MTS (Moscow, Russia)
6150/NWGSM (St. Petersburg, Russia)
6150/NetCom GSM (Norway)
6130/IDEA Centertel (Poland) (GSM 1800)
6110/Paegas (Czech Republic)
6110/Panafon (Greece)
6110/Telstra Mobilenet (Australia)
5110/Omnitel (Italy)
5110/Paegas (Czech Republic)
5110/ERA GSM (Poland)
5110/Plus GSM (Poland)
5130/IDEA Centertel (Poland)
5190/Microcel (Canada) (GSM 1900)

3210 (some functions does not not work yet)

2110 Series

6160 Series

640 Series


- 14.0 Credits -
  
Please take a moment to read the CREDITS file which endeavors
to recognise those who have helped so far!


- 15.0 Release Notes -
20020213 Version 0.3.4
Security bugfix release. See the RELEASE_NOTES for the detailes.

20010627 Version 0.3.3
Many 6110 series updates: mainly in SMS, bitmaps and ringtones handling.
Better localization. Integrated xlogos with xgnokii. Documentation updates.
Probably the last 0.3 series release.

20000520 Version 0.3.2
We have data calls and autoconf.  Nuff said :)

19991222 Version 0.3.1
Interim release to bring released code into line with latest CVS
offerings.

19990824 Version 0.3.0
6110 functionality has increased again, details of which are
in the 6110 specific readme.  Few minor tweaks on the 3810
side but we've just about run out of things the 3810 can do
(data and fax calls aside of course!)

This release is the first to include xgnokii - an X based
interface to your phone and gnokiid - the makings of a
virtual modem/AT emulator interface.  Details of these
two apps appear above.

19990519 Version 0.2.5
Little has changed on the 3810 side - mostly adding stub functions
to stay current with the 6110 code.  A no-brainer bug was found in 
the SMS send routines which is now corrected - could have caused
multiple messages to be sent.

6110 support has moved ahead in leaps and bounds, SMS sending is
now in there along with many other new function.

19990328 Version 0.2.4
Largely a synchronisation release to incorporate Pavel's numerous
patches for 6110 support and internationalisation (such a long
word, i18n is better :-).

Added SMS delete function for 3810 series.

19990305 Version 0.2.3
Added gsm-api.c/.h and gsm-common.h as a standard interface and
set of datatypes that can be used across multiple models.  This
API is still a work in progress.

Changed references to "handset" to "phone" to ensure a consistent
nomenclature.

Phonebook is now dumped with words int or sim for memory type
rather than a numeric value.

19990219 Version 0.2.2
Fixed bug and added support to display bytes returned when
the link is initialised.  If you see something other than the
values noted in fbus.c, please let me know and include
your phone type and software version.

Added initial cut of SMS send capability.  Caveats are
discussed above.

Added two different default values for length of phonebook
name and numbers.  These are selected according to whether
internal or SIM memory is specified.

Fixed bugs reported in 0.2.1 (errno.h and reversal of message
center and sender fields)

19990216 Version 0.2.1
Fixed bug that caused phone book entries containing spaces to be
mangled.  Added retrieve SMS message function.

19990213 Version 0.2.0
First version that looks more like the finished product - supports
command line options etc. 

19990126 Version 0.1.0
Initial release of monitoring tool - first rough incarnation of
gnokii - what will ultimately be the monitoring and programming tool.
