- G N O K I I - (C) 1999 - 2003 Hugh Blemings & Pavel Janík ml. (C) 2001 - 2004 Pawe³ Kot Last update 22 February 2004 Version 0.6.0 - 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.6.0 of gnokii, a multisystem tool suite and modem driver for the 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 :). Primary gnokii goal was to support Nokia phones, but currently we support all AT command compliant phones through the atgen driver. gnokii supports most Nokia phones from the 3110/3180, 5110/6110, 7110/6210 and 6510/6310 series, details including bugs specific to each series appear in the files README-3810, README-6110, README-7110 and README-6510 respectively. Also all AT compatible phones are supported. 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://www.gnokii.org/ which amongst other things gives information on how to join the gnokii mailing list, retrieving bleeding edge releases through CVS and more! - 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. The second application provided is xgnokii which as the name suggests is a X Window System 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. 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. Currently gnokiid is only useful for old Nokia phones from 6100 series that didn't include AT commands support. This includes Nokia 61X0 and 51X0 models. Don't use it with other phones. 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. - 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, README-2110 for notes on the 2110 series (which is at the moment deprecated), README-7110 for notes on 7110/6210 series and README-6510 for notes on the 6510/6310 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 the script 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.6.0-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 the appropriate README file. 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/IrDA/bluetooth link is working is to run gnokii with the --identify flag e.g. foobar$ gnokii --identify This will attempt to connect to your phone and display the basic information about the phone: manufacturer, phone model, firmware version and IMEI. If you get an error along the lines of Telephone interface init failed: [...]. Quitting. this indicates that gnokii could not communicate with your phone for some reason and you will need to do some troubleshooting. As the other test you may try: foobar$ gnokii --monitor which should show you some other information like memory usage or signal strength. - 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 common/phones/*.c and include/phones/*.h 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. When gnokii receives the frame with the unknown meaning it stores the frame and the triggering frame to $HOME/.gnokii-errors file. Report it! 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 source of gnokii aplications is in the CVS server. The server's address is savannah.nongnu.org. If you are already familiar with CVS, set the CVSROOT to :ext:anoncvs@subversions.gnu.org:/cvsroot/gnokii and CVS_RSH to ssh, and using ssh protocol v2, check 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 up your ssh client to connect to savannah servers using ssh v2 protocol. Put: Host savannah.nongnu.org Protocol 2 into your ssh configuration (~/.ssh/config) 2. Set your environmental variable CVS_RSH (remote shell command). If you have bash (Bourne Again Shell): export CVS_RSH=ssh If you have different shell, use different command (e.g. setenv). 3. Set your environmental variable CVSROOT. If you have bash (Bourne Again Shell): export CVSROOT=:ext:anoncvs@savannah.nongnu.org:/cvsroot/gnokii If you have different shell, use different command (e.g. setenv). 4. 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://savannah.nongnu.org/cgi-bin/viewcvs/gnokii/ Once you have the sources, you will need to run the following commands gettextize aclocal autoheader autoconf ./configure make or just issue sh autogen.sh 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, subscribe to gnokii-commit mailing list at http://mail.nongnu.org/mailman/listinfo/gnokii-commit. Our thanks go to the Czech Linux Users Group for hosting the original CVS repository at cvs.linux.cz and then to the Samba Team who kept hosting our CVS for the several years at cvs.samba.org. - 11.0 Protocol Details - You'll find the detailed protocol description in Docs/protocol/ directory. - 12.0 References - The web site for this project is at; Project page on savannah is at The mailing list devoted to the gnokii project is You can subscribe at The serial programming how-to was valuable in cobbling together serial code for both monitoring and the tools themselves. - 13.0 Handsets tested - Nokia 3810 Series + 3110 + 3810 + 8110 + 8110i Nokia 6110 Series + 3210 + 3310 + 3330 + 3360 + 3390 + 3410 + 5110 + 5130 + 5190 + 6110 + 6130 + 6150 + 6190 + 8210 + 8250 + 8290 Nokia 7110 Series + 6210 + 6250 + 7110 + 7190 Nokia 6510 Series + 5100 + 6100 + 6310 + 6310i + 6360 + 6510 + 6610 + 8310 Nokia 2110 Series - deprecated Nokia 6160 Series (limited functionality) + 5120 + 6160 Nokia 640 Series - deprecated AT series + Bosch 908/909 + Motorola Timeport P7389i (L series), C350 + Nokia 6210/7110/8210/6310(i)/6510/9210/7650/3650 + Siemens S25/SL45i/C55/M55/S55 + Sony Ericsson T68i - 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 - 20040222 Version 0.6.0 Bugfixes in phonebook handling (import and export should work now correctly, gnokii and xgnokii share the formats), calendar handling, sending unicode short messages (chinese texts should be sent correctly), msvc6 build. Set correctly Nokia 8310 information (logo sizes, signal indicator). Updates to documentation. Debug can be turned on in the config unless it was explicitely disabled with --enable-debug=no. 20040201 Version 0.5.10 Few bugfixes: ucs2 encoding and decoding, phonebook subentries, at driver responses handling. New features: answer/cancel call for AT driver, delete phonebook entry. Besides many documentation updates and build fixes. 20040119 Version 0.5.9 We disabled Nokia 6100 support as it is known to break the phone with the gnokii communication over the irda port. All tested firmwares seem to be vulnerable. We're working on the real fix. Besides many bugfixes. We focused on build problems. Also some code improvements: fix memory leaks and somesegfaults, fix --playringtone incorrect behaviour, fix large calendar reading. 20040101 Version 0.5.8 Many cleanups and build fixes (some of them taken from FreeBSD ports). Updated GSM operator list. Fixes in gnokii behaviour. New commands for AT driver. 20031216 Version 0.5.7 Support for Bluetooth on MacOS X and FreeBSD. Many fixes: phone lockups, utf8 encoding, ringtones. Some new features for different drivers were implemented. Updates for win32 build. 20031108 Version 0.5.6 Many bugfixes. Ringtone editor in xgnokii is fully functional. Ringtone support is enhanced in the nk6100 and nk6510 drivers. A lot of datacall related updates (RLP bugfixes, AT emulator enhanced). vCard and LDIF addressbook export is working again. 20031008 Version 0.5.5 Bugfix release, focus mainly on the ringtone features. Some new functions added wrt ringtones. 20030922 Version 0.5.4 Win32 port update and other small bugfixes. 20030921 Version 0.5.3 Many bugfixes. Added missing manual pages. Updates to nk3110, nk6100 and nk6510 drivers. New functionality: possibility to exchange addressbook in the LDIF format (used by Mozilla Mail), playringtone. 20030613 Version 0.5.2 Few more bugfixes. French translation. Updates to nk3110 and nk6100 drivers functionality. 20030529 Version 0.5.1 This is mainly maintanance release fixing few bugs found. 20030512 Version 0.5.0 The external API was rewritten. Now it should be easier to write any external application using libgnokii. Many bugfixes and code cleanups. Improved build system. Better portability to *BSD, MacOSX and Windows. Allow to use multiple phones. Bluetooth support. New helper applications: ppm2nokia. Much improved nk3110, nk6510 and AT support. 20020805 Version 0.4.3 Many functional updates. They touch mainly nk6510 and nk6110 drivers functionality, also updates in nk7110 driver. Add new functionality to gnokii/xgnokii (TODO list). More phone models are known to work. SMSD should work with the drivers supporting SMS folders. 20020722 Version 0.4.2 Minor updates. Mainly fixes and updates in nk6510 driver: sms sending and reading, dlr3p cable support. sendsms can recognize messages not written in the default alphabet and automatically sends them in unicode. Also many reported nasty bugs fixed. 20020714 Version 0.4.1 Minor but valuable updates. Many improvments in nk6310 driver (Nokia 6310, 6510 and 8310), small improvements in nk6160 and nk7110 drivers, more verbose output for gnokii command line output, documentation updates containing FAQ updates, SMS sending timeout is now configurable, flex will not be required to build gnokii from the tarball and other minor fixes. 20020710 Version 0.4.0 Major rewrite. Internal API completly changed. Added support fot the new phones, maily Nokia 6210, Nokia 7110, Nokia 6310, Nokia 6510 and AT compatible not-only-Nokia phones. We got new libgnokii, that can be used for creating any user application, smsd -- sms handling daemon, libsms -- first step to extract a middle layer, many new options to command line gnokii and many others. Refer to the ChangeLog for the detailes (unfortunately it starts with 0.4.0pre9 version) 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.