                            - G N O K I I -
              (C) Hugh Blemings & Pavel Jank ml. 1999
               Last update 22 December 1999  Version 0.3.1

- Contents - 			   

1.0  Introduction
2.0  General Notes
3.0  Notes for 3810 Series
4.0  Notes for 6110 Series
5.0  Installation
6.0  Known Bugs
7.0  Gnokii and Perl
8.0  How to help
9.0  gnokii by CVS
10.0 Protocol Details
11.0 References
12.0 Handsets/Networks tested
13.0 Credits
14.0 Release Notes

			   
- 1.0 Introduction -

This is version 0.3.1 of gnokii, a Linux/Unix tool suite and (soon!)
modem/fax driver for Nokia mobile phones, released under the GPL.  Please
see COPYING for more details on license/copying issues as well as the
(lack of) warranty.  This is an "interim release" largely to bring
the released code up to date with what is in CVS.

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

Note that it is still not possible to make fax or data calls on either
series of phones.  We are getting closer though!

As you may be aware, there were indications that Nokia may provide
some support for the project.  Regrettably, these negotiations have
pretty much stalled over the issue of binary versus open source releases.

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 General notes -
  
gnokii now consists of three main executables and a fourth "helper"
application that is run suid root.

The first, gnokii is a command line utility primarily for exercising
the api functions that have been written.  Many people now use it
for reading/writing phone book entries, sending and receiving SMS 
messages etc. etc.  Ultimately however 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.
For now though, gnokii provides the main stable interface to your
phone.

Secondly, xgnokii is as the name suggests an X-windows based application
that provides a graphical interface to your phone.  It is still in its
early days but gives a good indication of where things are heading!
At present xgnokii also 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 is under heavy
development, it's ultimate aim being to act as a 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.)

gnokiid's second and perhaps more important role is to provide a virtual
modem interface /dev/gnokii that looks like an ordinary Hayes-AT
compatible modem.  It will support the more important AT commands
for SMS and phone book manipulation as well as (ultimately) data
and fax call setup/teardown.  This code is still in its infancy
but some basic AT commands are now available.

The helper application, mgnokiidev is used to create on demand
a symbolic link between /dev/gnokii and the pseudo tty used
by gnokiid for the virtual modem interface.

- 3.0 Notes for 3810 Series -
  
Please see the README-3810 file.


- 4.0 Notes for 6110 Series -
  
Please see the README-6110 file.


- 5.0 Installation -

Review the Makefile and make sure that the MODEL and PORT defines
are correct for your setup.  These values are used as defaults
in the absence of a ~/.gnokiirc file.   Note that you will 
need permissions on whatever serial port you select.

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.

Copy the sample.gnokiirc file to your home directory and name
it .gnokiirc  Edit the settings in this file to suit your
setup.

Type make, all should build from there, it's pretty simple code
so you shouldn't have any problems.  Note that you need pthread
libraries, they are standard on most modern Linux distributions.
Note that gnokii is not only for Linux - you can use it on
FreeBSD and similar systems too.

In order to make use of the AT emulator through /dev/gnokii,
you must;

* Create a group called gnokii (edit /etc/group).
* Ensure you are in the gnokii group.
* Ensure that the mgnokiidev executable has permissions 4754
* Ensure that mgnokiidev is owned by root and in group gnokii.

- 6.0 Known Bugs -

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

Note there are a couple of patches that have been sent in (to Hugh)
for the 3810 and/or pseudo tty code that haven't made it in yet. 
New parent syndrome...


- 7.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


- 8.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]  Both 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.

- 9.0 gnokii by CVS -

The gnokii project now has a CVS server,  served by the Czech Linux
Users' Group. The server's address is cvs.linux.cz. If you are
already familiar with CVS, set the CVSROOT to 

	:pserver:cvs@cvs.linux.cz:/cvs/gnokii

and use an empty password for checkout the repository with the name
gnokii.

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

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

	export CVSROOT=:pserver:cvs@cvs.linux.cz:/cvs/gnokii

	   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 an empty password.


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

	cvs co gnokii

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

http://odysseus.fi.muni.cz/cgi-bin/cvsweb.cgi/?cvsroot=gnokii

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@linuxcare.com)
and you'll be added to the recipients list.


- 10.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.



- 11.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>


- 12.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)
5130/IDEA Centertel (Poland) (GSM 1800)
5190/Microcel (Canada) (GSM 1900)



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


- 14.0 Release Notes -
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.
