Docs/README

   1                               - G N O K I I -
   2              (C) 1999, 2000, 2001 Hugh Blemings & Pavel Janík ml.
   3                             (C) 2001 Pawe³ Kot
   4                   Last update 27 Sep 2001    Version 0.3.3
   5
   6 - Contents -
   7
   8 1.0   Introduction
   9 2.0   About the applications
  10 3.0   Notes for specific model phones
  11 4.0   Installation from source
  12 5.0   Installation of pre-built binaries
  13 6.0   Configuration
  14 7.0   Known Bugs
  15 8.0   Gnokii and Perl
  16 9.0   How to help
  17 10.0  gnokii by CVS
  18 11.0  Protocol Details
  19 12.0  References
  20 13.0  Handsets/Networks tested
  21 14.0  Credits
  22 15.0  Release Notes
  23
  24
  25 - 1.0 Introduction -
  26
  27 This is version 0.3.3 of gnokii, a Linux/Unix tool suite and modem
  28 driver for Nokia mobile phones, released under the GPL.  Please
  29 see COPYING for more details on license/copying issues, the lack of
  30 warranty and where to send a postcard if you like gnokii :).  This
  31 release provides the much awaited ability to place data calls for
  32 all platforms except Win32.  Fax calls are not supported.
  33
  34 gnokii supports most phones from the 3810/8110, 5110/6110, and 2110
  35 series, details including bugs specific to each series appear in the
  36 files README-3810, README-6110 and README-2110 respectively.
  37
  38 In the early stages of the project there were indications that
  39 Nokia would provide some support for the project.  Regrettably, these
  40 negotiations stalled over the issue of binary versus open source
  41 releases and the project has proceeded without official or unofficial
  42 assistance.
  43
  44 We have a web site at http://gnokii.org which amongst other things
  45 gives information on how to join the gnokii mailing list, retrieving
  46 bleeding edge releases through CVS and more!
  47
  48 If you haven't already done so, please indicate your interest in
  49 the gnokii project by adding yourself to the user database
  50 at http://gnokii.org/users
  51
  52
  53 - 2.0 About the applications -
  54
  55 gnokii now consists of three main executables and a fourth "helper"
  56 application that is run suid root.  To get the most from gnokii it
  57 is worth understanding the details of them and how they interact.
  58 It is important to note that at present you cannot run more than
  59 one of gnokii, xgnokii or gnokiid at a time.
  60
  61 The first application, gnokii, is a command line utility that was
  62 originally provided to assist developers and interested users in
  63 working with the low level API functions that were being developed.
  64
  65 From these rather humble beginnings, it has evolved into a the main
  66 command line tool of the suite.  Many people now use it for
  67 reading/writing phone book entries, sending and receiving SMS messages
  68 etc.  Ultimately it is intended that it will become a utility that
  69 communicates with gnokiid to provide a command line interface to
  70 the functionality provided by the gnokiid daemon.
  71
  72 The second application provided is xgnokii which as the name suggests
  73 is a X-windows based application that provides a graphical interface
  74 to your phone.  Amongst other things, xgnokii allows you to read and
  75 write phone book entries, read, write and send SMS messages, monitor
  76 battery and received signal strength.
  77
  78 At present xgnokii works directly with the phone, however in the
  79 future it will more likely use the "side" interface of gnokiid.
  80
  81 The third part of the suite is gnokiid.  gnokiid provides a
  82 virtual modem interface, /dev/gnokii that looks like a regular
  83 Hayes-AT compatible modem with the ETSI defined extensions for
  84 GSM phones.  What this means in practical terms is that you can
  85 treat the /dev/gnokii device like an ordinary modem and use it
  86 to make data calls from pppd or a terminal application like
  87 minicom.
  88
  89 gnokiid is still under development, it's ultimate aim being to
  90 act as a "master" daemon that interfaces with your phone on one
  91 side and gnokii or xgnokii on the other.  This "side" code is still
  92 under discussion, particularly with respect to the most appropriate
  93 choice of communication method (IPC, TCP/IP etc.)
  94
  95 The last application provided with the suite is mgnokiidev which is
  96 used by gnokiid to create on demand a symbolic link between
  97 /dev/gnokii and the pseudo tty used by gnokiid for the virtual
  98 modem interface.  It's operation is transparent under normal
  99 usage as gnokiid takes care of calling it when required.
 100
 101 You should be aware of a minor security hole in mgnokiidev -
 102 members of the 'gnokii' group may be able to use it as a way
 103 to access pseudottys in use by other users on the system.  If
 104 you are the only user on your system, or you trust anyone that
 105 you put into group gnokii you have no problem.  If this isn't
 106 the case contact one of the authors who will try and suggest
 107 a workaround.  It is expected that this problem will be fixed
 108 in the next release of gnokii.
 109
 110
 111 - 3.0  Notes for specific model phones -
 112
 113 Please see the README-3810 file for notes specific to the
 114 3810/8110 series, README-6110 for notes on the 5110/6110
 115 series and README-2110 for notes on 2110 series.
 116
 117
 118 - 4.0 Installation from source -
 119
 120 gnokii makes use of autoconf/automake which allows you to configure
 121 the source tree for your system by typing
 122
 123 ./configure
 124
 125 You can also run configure with the --help flag to get a list of
 126 available options.  There are about a dozen or so that are specific
 127 to gnokii.
 128
 129 Once you've run ./configure successfully, you should be able to
 130 simply do a make and make install to compile and install your
 131 binaries respectively.
 132
 133 make
 134
 135 make install
 136
 137 With this done you've built and installed your binaries, and
 138 should proceed to the configuration section below.
 139
 140
 141 - 5.0 Installation of pre-built binaries -
 142
 143 If you downloaded gnokii as a pre-built binary you should install
 144 it in the conventional manner for the package type in question.
 145 For example if you downloaded a .rpm file you can install it by
 146 running the following as root.
 147
 148 rpm -i gnokii-0.3.3-i386.rpm
 149
 150 If you are using a Debian based system, you can use dpackage
 151 to do the installation. On Slackware you use installpkg or pkgtool.
 152
 153
 154 - 6.0 Configuration -
 155
 156 Once you have installed the binaries, you should copy the
 157 sample/gnokiirc file from the Docs directory to your home
 158 directory and name it .gnokiirc  Using your favorite editor
 159 ensure that the settings are correct for your system, the sample
 160 file has details of the various options available.
 161
 162 If you used a pre-built version of gnokii (.rpm, .deb etc) it
 163 may have installed a /etc/gnokiirc file.  If it has, the
 164 settings in this file will be used in the absence of a
 165 .gnokiirc file in your home directory.
 166
 167 Note that you will need read/write permissions on whatever
 168 serial port you specify in .gnokiirc.  You can now use gnokii
 169 and xgnokii.
 170
 171 Review the notes specific to your model of phone in either
 172 README-6110 or README-3810 as appropriate.  These files
 173 also provide information about what functionality is
 174 available for each model.
 175
 176 In order to make use of the AT emulator provided by gnokiid
 177 through /dev/gnokii, you must read the documentation file
 178 DataCalls-QuickStart.
 179
 180 A simple test to confirm that your cable/IR link is working
 181 is to run gnokii with the --monitor flag e.g.
 182
 183   foobar$ gnokii --monitor
 184
 185 This will attempt to connect to your phone and display
 186 information such as signal strength, battery level  etc.
 187
 188 If you get an error along the lines of
 189
 190   Hmmm... GSM_LinkOK never went true. Quitting.
 191
 192 this indicates that gnokii could not communicate with your phone
 193 for some reason and you will need to do some troubleshooting.
 194
 195
 196 - 7.0 Known Bugs -
 197
 198 Review the bugs section in the README for your series of phone.
 199
 200 Note the possible security hole in mgnokiidev discussed above.
 201
 202
 203 - 8.0 Gnokii and Perl -
 204
 205 There is a perlmodule available for gnokii. It gives access to all
 206 the routines that are defined in gsm-common.h from a perl-program. It
 207 is intended for application developers who want to use their favorite
 208 language in interfacing the phone data with databases, ldap-directories
 209 and (in the future) different calendar applications. It is written by
 210 Konstantin Agouros (konstantin@agouros.de) and support starts with
 211 revision 0.2.6-pre3 of gnokii.
 212
 213 The homepage of this module is http://www.agouros.de/gnokii
 214
 215
 216 - 9.0 How to help -
 217
 218 There are a number of ways you can help out.
 219
 220 Code specific to each model is contained within fbus-3810.[ch] and
 221 fbus-6110.[ch] and other [fm]bus-*.[ch] files. All command handlers
 222 will dump information to stderr when they encounter a message they don't
 223 understand.  If this happens to you, try and work out what is going on.
 224
 225 Suggestions on changes to the code are welcome, the preference is that
 226 they be aired on the mailing list so that a consensus can be reached
 227 when appropriate.  This is particularly important if you intend making
 228 large changes and/or submitting big patches.
 229
 230 - 10.0 gnokii by CVS -
 231
 232 The gnokii project has a new CVS server thanks to Andrew Tridgell
 233 and the Samba team.  The server's address is pserver.samba.org.  If you
 234 are already familiar with CVS, set the CVSROOT to
 235
 236         :pserver:cvs@pserver.samba.org:/cvsroot
 237
 238 and use the password cvs for checking out the repository with the name
 239 gnokii.
 240
 241 If you are not familiar with cvs, don't worry. It's very simple.
 242 Just install the cvs package for your distribution and follow these steps:
 243
 244         1. set your environmental variable CVSROOT. If you have bash (Bourne
 245            Again Shell):
 246
 247         export CVSROOT=:pserver:cvs@pserver.samba.org:/cvsroot
 248
 249            If you have different shell, use different command (e.g. setenv).
 250
 251
 252         2. Log in to the CVS server as anonymous reader by typing
 253
 254         cvs login
 255
 256            Use 'cvs' as your password.
 257
 258
 259         3. If you are logged in you are ready to checkout the latest sources:
 260
 261         cvs co gnokii
 262
 263 If you prefer, there is a WWW interface to the CVS server at
 264
 265 http://pserver.samba.org/cgi-bin/cvsweb/gnokii/
 266
 267 Once you have the sources, you will need to run the following commands
 268
 269         autoconf
 270         ./configure
 271         make
 272
 273 to build the sources.
 274
 275 Now you are on your own - you have the current sources on your disk
 276 in the directory gnokii.  If you are going to make substantial changes
 277 and feel that they should be included into gnokii please mention it
 278 on the list first to avoid duplicated effort.
 279
 280 If you would like to receive email when updates are made to the CVS
 281 repository, just send Hugh and email to that effect (hugh@blemings.org)
 282 and you'll be added to the recipients list.
 283
 284 Our thanks go to the Czech Linux Users Group for hosting the original
 285 CVS repository at cvs.linux.cz.
 286
 287 - 11.0 Protocol Details -
 288
 289 3810 Series
 290
 291 The protocol used between the phone and the PC has been worked out
 292 by a mixture of trial and error, monitoring the data that goes between
 293 the 3810 and its Windows 95 software and a few snippets of information
 294 found on the 'net relating to older Nokia models.  Feedback from
 295 people who played with the first release of gnokii was invaluable.
 296
 297
 298 6110 Series
 299
 300 The same applies for 6110 Series (but I use Windows NT 4.0 for
 301 monitoring). The protocol of 6110 Series is somewhat different from 3810
 302 Series. Perhaps the first draft of the protocol for communication between
 303 Nokia mobile phones and PCs was not so general to support the newest features
 304 of Nokia's phones.
 305
 306 You'll find the detailed protocol description in Docs/protocol directory/
 307
 308 - 12.0 References -
 309
 310 The web site for this project is at;
 311
 312         http://gnokii.org
 313
 314 The mailing list devoted to the gnokii project is
 315
 316         <gnokii@net.lut.ac.uk>
 317
 318 You can subscribe by sending an email to
 319
 320         <gnokii-request@net.lut.ac.uk>
 321
 322 with the word subscribe in the body.
 323
 324 The serial programming how-to was valuable in cobbling together
 325 serial code for both monitoring and the tools themselves.  This
 326 is the Australian mirror, there will be one nearby to you too :)
 327
 328 <http://www.monash.edu.au/mirror/ldp/HOWTO/Serial-Programming-HOWTO.html>
 329
 330
 331 - 13.0 Handsets/Networks tested -
 332
 333 3810 Series
 334
 335 3110/Sonera (Finland)
 336 3110/Telefonica (Spain)
 337 3810/Telstra (Australia)
 338 3810/Optus [Actually Hutchison] (Australia)
 339 3810/Mobile One (Singapore)
 340 3810/SingTel Mobile (Singapore)
 341 8110/Proximus (Belgium)
 342 8110/D2 Privat (Germany)
 343 8110i/MTN (South Africa)
 344 8110/Beeline Vympelkom (Russia)
 345 8110i/A1 Mobilkom (Austria)
 346
 347 6110 Series
 348
 349 6190/Microcel (Canada) (GSM 1900)
 350 6150/Viag Interkom (Germany) (GSM 1800)
 351 6150/Omnitel (Italy)
 352 6150/Beeline (Vympelkom) (Moscow, Russia)
 353 6150/MTS (Moscow, Russia)
 354 6150/NWGSM (St. Petersburg, Russia)
 355 6150/NetCom GSM (Norway)
 356 6130/IDEA Centertel (Poland) (GSM 1800)
 357 6110/Paegas (Czech Republic)
 358 6110/Panafon (Greece)
 359 6110/Telstra Mobilenet (Australia)
 360 5110/Omnitel (Italy)
 361 5110/Paegas (Czech Republic)
 362 5110/ERA GSM (Poland)
 363 5110/Plus GSM (Poland)
 364 5130/IDEA Centertel (Poland)
 365 5190/Microcel (Canada) (GSM 1900)
 366
 367 3210 (some functions does not not work yet)
 368
 369 2110 Series
 370
 371 6160 Series
 372
 373 640 Series
 374
 375
 376 - 14.0 Credits -
 377
 378 Please take a moment to read the CREDITS file which endeavors
 379 to recognise those who have helped so far!
 380
 381
 382 - 15.0 Release Notes -
 383 20010627 Version 0.3.3
 384 Many 6110 series updates: mainly in SMS, bitmaps and ringtones handling.
 385 Better localization. Integrated xlogos with xgnokii. Documentation updates.
 386 Probably the last 0.3 series release.
 387
 388 20000520 Version 0.3.2
 389 We have data calls and autoconf.  Nuff said :)
 390
 391 19991222 Version 0.3.1
 392 Interim release to bring released code into line with latest CVS
 393 offerings.
 394
 395 19990824 Version 0.3.0
 396 6110 functionality has increased again, details of which are
 397 in the 6110 specific readme.  Few minor tweaks on the 3810
 398 side but we've just about run out of things the 3810 can do
 399 (data and fax calls aside of course!)
 400
 401 This release is the first to include xgnokii - an X based
 402 interface to your phone and gnokiid - the makings of a
 403 virtual modem/AT emulator interface.  Details of these
 404 two apps appear above.
 405
 406 19990519 Version 0.2.5
 407 Little has changed on the 3810 side - mostly adding stub functions
 408 to stay current with the 6110 code.  A no-brainer bug was found in
 409 the SMS send routines which is now corrected - could have caused
 410 multiple messages to be sent.
 411
 412 6110 support has moved ahead in leaps and bounds, SMS sending is
 413 now in there along with many other new function.
 414
 415 19990328 Version 0.2.4
 416 Largely a synchronisation release to incorporate Pavel's numerous
 417 patches for 6110 support and internationalisation (such a long
 418 word, i18n is better :-).
 419
 420 Added SMS delete function for 3810 series.
 421
 422 19990305 Version 0.2.3
 423 Added gsm-api.c/.h and gsm-common.h as a standard interface and
 424 set of datatypes that can be used across multiple models.  This
 425 API is still a work in progress.
 426
 427 Changed references to "handset" to "phone" to ensure a consistent
 428 nomenclature.
 429
 430 Phonebook is now dumped with words int or sim for memory type
 431 rather than a numeric value.
 432
 433 19990219 Version 0.2.2
 434 Fixed bug and added support to display bytes returned when
 435 the link is initialised.  If you see something other than the
 436 values noted in fbus.c, please let me know and include
 437 your phone type and software version.
 438
 439 Added initial cut of SMS send capability.  Caveats are
 440 discussed above.
 441
 442 Added two different default values for length of phonebook
 443 name and numbers.  These are selected according to whether
 444 internal or SIM memory is specified.
 445
 446 Fixed bugs reported in 0.2.1 (errno.h and reversal of message
 447 center and sender fields)
 448
 449 19990216 Version 0.2.1
 450 Fixed bug that caused phone book entries containing spaces to be
 451 mangled.  Added retrieve SMS message function.
 452
 453 19990213 Version 0.2.0
 454 First version that looks more like the finished product - supports
 455 command line options etc.
 456
 457 19990126 Version 0.1.0
 458 Initial release of monitoring tool - first rough incarnation of
 459 gnokii - what will ultimately be the monitoring and programming tool.