gnokii logo Open source tools for your mobile phone
Current gnokii version: 0.6.31
One time support for gnokii:

Getting started

  1. General information
  2. Nokia phones
  3. Symbian phones
  4. Max OS X support
  5. Windows support

General Information

Introduction

This is version 0.6.22 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. Moreover version 0.6.1 brings support for Symbian-based phones.

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.

About the applications

gnokii project provides now several suprojects and several programs in them. The most important project provides libgnokii and core applications using it. To get the most from gnokii it is worth understanding the details of them and how they interact.

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.

gnokiid makes use of the small helper application called mgnokiidev. It creates on demand a symbolic link between /dev/gnokii and the pseudo tty used by gnokiid for the virtual modem interface. Its operation is transparent under normal usage as gnokiid takes care of calling it when required.

The last application within the main gnokii project is smsd, a deamon that simplifies operation of sending and receiving SMSes to the database operations.

There are several gnokii subprojects which are worth mentioning.

gnocky is an alternative GTK2 phone manager suite, thought as a replacement for xgnokii, however not yet that powerful.

gnokiifs provides a filesystem access to the phone filesystem (if the phone supports it) on top of libgnokii. You may need this just when the phone doesn't support Obex protocol.

gnapplet is a phone driver for the Symbian phones. This is at the moment the only way we can access various data on such phones as AT capabilites of Symbians are very limites (you can access them also with SyncML getting some more information).

gnokii-artwork contains some images and pixmaps that may be used by xgnokii and other GUIs. They are put into the separate module because we are not sure about the licensing.

gnokii-extras contains sample applications (some of them really useful!) demonstrating how to use libgnokii.

There are also several third-party applications using libgnokii, including: kdepim (distributed within KDE), Multisync and Opensync (as a plugin), GNOME PhoneManager, Maemo's PhoneLink, qnokii.

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. See our wiki site for the working examples of the config settings.

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. Sample gnokiirc provided with gnokii sources provides many examples and explanations.

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.

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

Please note that Perl binding has not been updated for some time and may not work with current libgnokii.

Gnokii and PHP

Daniele Forsi prepared PHP bindings for libgnokii. It should be mostly up-to-date and supports most of the useful things that you might use from a webpage.

You can find more information about gnokiiphp at Daniele's site.

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.

Nokia 6510 series

Driver name: nk6510
List of supported models (incomplete): 6510, 6310, 8310, 6310i, 6360, 6610, 6100, 5100, 3510, 3510i, 3595, 6800, 6810, 6820, 6820b, 6610i, 6230, 6650, 7210, 7250, 7250i, 7600, 6170, 6020, 6230i
All Nokia Series40 phones should work with this driver.

Code for the 6510 phones has been tested with DAU-9P and DLR-3P cables and IrDA connection. The following conection type values are recommended for the various connection media:

MediaConnection type
dau9pdau9p or serial
dlr3pdlr3p
IrDAirda
Bluetoothbluetooth

When you don't know what your cable is you can first try serial value.

The current code is able to:

  • identify the phone ;-)
  • read/write phonebook entries
  • read SMS messages of all kinds
  • read SMS centers
  • send basic text messages
  • read/write calendar entries
  • read the memory status
  • read/write bitmaps (group, operator logos)
  • read network info
  • read RF/battery level
  • read date/time
  • read list of ringtones
  • read/write profiles
  • read WAP bookmarks/settings
  • read/write/delete ToDo entries
  • create/delete SMS folders
  • save SMS messages to phone (may be dangerous)

Hint: For all these phones you can also use AT driver, as they all have a builtin hardware modem.

Nokia 7110 series

Driver name: nk7110
List of supported models (incomplete): 7110, 6210, 6250, 7190
Probably also other phones will work with them. If you know such model, please let us know.

Another Nokia phones series, another protocol. These phones seems to be the most popular at the moment, but probably for not more the one year more. Anyway the support for them is quite complete, but not complete yet. We hope to finish soon.

This driver was tested and is known to work with DAU-9P and DLR-3[P] cables and IrDA connection. As the side note, remember that to get the faster initialization with DAU-9P cable use 'connection = dau9p' instead of 'connection = serial' in the config file. For IrDA use 'connection = irda', not 'connection = infrared'.

Hint: For all these phones you can also use AT driver, as they all have a builtin hardware modem, which may give you more functionality for the moment.

Nokia 6110 series

Driver name: nk6100
List of supported models: 6110, 6130, 6150, 6190, 5110, 5130, 5190, 3210, 3310, 3330, 3360, 3390, 3410, 8210, 8250, 8290, 8850, RPM-1

Code for the 6110 phones has been tested with the DAU-9P MBus Cable NSE-3.

Phones of 6110 Series have somewhat different protocol then other Nokia phones series. More detailes on the protocol you'll find in the Docs/protocol/nk6110.txt file inside the gnokii sources.

The current code allows you to do almost everything you are able to do with these phones. It covers SMS, phonebook, calendar operations and much, much more.

There are some problems with the few firmwares (V 05.24). It seems that these firmware is weird. If you have a Nokia with this firmware, it accepts the PIN request (displays Code Accepted message) but nothing is returned to the PC. The communication is only in one direction :-( I do not know why. If you can help with this, please let me know.

Nokia 3810 series

Driver name: nk3110
Supported models: 3110, 3810, 8110, 8110i

Phones in the 3810 series that have been tested to date are 3110, 3810, 8110, 8110i with either the DAU-4F cable or in one or two cases a home made cable. Specific phone/ network combinations appear in the main README file.

After some digging in to the protocol it has become apparent that there aren't many more functions we can support, compared to our 5110/6110 cousins! Remaining functionality which I would like to add appears in the To-do section below, suggestions are welcome.

The code for reading/writing phonebook entries has had limited testing but the read code is believed to be solid. It has been observed that the write code occasionally fails to write a location for reasons as yet unknown. The format of the input to the write option is relatively unforgiving and does only very basic parsing. This format should be compatible with the output from the Windows NCDS software.

Routines for retrieving SMS messages have been tested and appear to be bug free. The 3810 used for testing appears to ignore the memory type field however.

Sending SMS is still something of "black art". This has been tested on a 3810 on the Australian Optus/Hutchison network. Most of the time the messages are sent as expected but occasionally they fail for no apparent reason. The code is designed to re-try up to four times before giving up if a 0x65 0x26 response is received.

Sometimes however error codes are seen 0x65 0xYY, the meaning of which is unknown. Any light you can cast on this is welcome. It is possible that switching off the phone and switching on again may help but this may be just a coincidence.

It should also be noted that the SMS header message sent by FB38_TX_Send0x23_SendSMSHeader code has no less than 10 bytes in it that aren't understood. The values used are simply those that have been observed. They may have to be totally different on your network :( They may inadvertently route the message to a distant land or just not work at all.

Having said all of the above about SMS sending, a number of people have now tested SMS sending on various networks around the world and in the main have found it to work correctly.

Functionality

The following functions/facilities are available for the 3810 series phones.

  • Retrieving and writing single or multiple phone book entries from either SIM or (in the case of the 8110s) internal memory.
  • Retrieving and deleting single or multiple stored SMS messages from either SIM or (again in the case of 8110s) internal memory.
  • Sending an SMS message to a specified recipient via a specified message center number.
  • By way of a message in --monitor mode, receive notification of the following occuring;
    • Incoming call being received, answered and hung up.
    • Outgoing call being made, answered and hung up.
    • Incoming SMS message
    • Current phone status (connected to network, call progress etc.)
  • Retrieve current RF and battery level
  • Retrieve IMEI, Model and Revision information

Known Bugs

fbus-3810 code cannot (yet) automatically determine the maximum length of the name and phone number fields in the SIM. Similarly it cannot yet determine the maximum number of SIM locations. These are defined in fbus-3810.h

The status (read or unread, sent or unsent) of SMS messages retrieved from memory is not known so these flags are always set to read / sent.

TODO

Add support to automatically determine the maximum number of SIM entries and lengths of phonebook and name fields.

Try building under Win32 and report success/failure to the list.

Nokia 2110 series

Driver name: nk2110
List of supported models: 2110, 2140, 6080

Code for the 2110 phones has been tested with home-built cable. It should work well with any sort of cable.

Known Bugs

Nokia protocol is not followed. We use hacks instead of collision detection protocol nokia suggests.

Many. Look at code, needs cleanup, etc. Contact pavel@ucw.cz if you want to help.

When periodically fetching messages, it gets to state where protocol breaks with "bad checksum".

TODO

SMS sending.

Implement functionanlity such as reading internal A/D convertors and ability to turn on netmon. [Not sure if all 2110s even have netmon.]

Nokia DKU2 cable

The recommended way to communicate over DKU-2 cable is to use gnokii userspace libusb driver. Ensure that you have libusb on your system (if you compile gnokii from the sources you need libusb development packages) and use

connection = dku2libusb

setting in your gnokiirc.

If for some reason you want to use Linux kernel driver read on.

The DKU2 cable, supplied for example with the nokia 7600/6230, is a straight-through lead which connects the phone to a USB port. By default, the usb device exposes two endpoints which provide AT-like modem emulation. This kernel module sets an alternative configuration to enable two further endpoints which enable Fbus communication.

Patches are in gnokii/patches. There is one for 2.4.22 - I expect it'll work with most 2.4 kernels, and one for 2.6.9.

The driver connects two ttys - after connecting the phone dmesg gives:

  Nokia AT Port:
  usbserial.c: Nokia 7600/6230 DKU2 driver converter now attached to ttyUSB0 (or usb/tts/0 for devfs)
  Nokia FBUS Port:
  usbserial.c: Nokia 7600/6230 DKU2 driver converter now attached to ttyUSB1 (or usb/tts/1 for devfs)

gnokii must be configured to use the second of these - in this case /dev/ttyUSB1

Install

  • Get / configure / build a set of kernel sources.
  • make sure that you are running this kernel, and /lib/modules/`uname -r`/build points to the kernel sources directory
  • cd $gnokii_sources/patches/kernel_2.{4,6}
  • make
  • Become root
  • make install
  • modprobe nokia_dku2
  • dmesg
  • Look for the lines as shown above!
  • Edit .gnokiirc to include port=/dev/ttyUSB.. and connection=dku2

Symbian phones

First of all, phones supported by this driver so far are all Symbian Series60 phones prior to 3rd Edition. Not supported are Symbian Series60 3rd Edition and Symbian Series80.

Most of the modern phones are based on the Symbian OS. These phones have broken the convention and replaced the traditional FBUS protocol framework by a new one. The new protocol provides synchronizational functionality, but the older one was more powerful. This is one of the reasons we decided that analysis of the new protocol is time wasting. Our plan is to create a client-server application. The client part is built into libgnokii, the server part runs on the phone. These communicate with our own protocol.

The client and the server application is tightly coupled, so you have to use the same version on both side. The source code of the server application (called gnapplet) is licensed under the GNU GPL, it can be downloaded from the gnokii cvs. Compiling gnapplet requires special tools, you can look into gnupoc. Installing the Nokia SDK isn't easy, so we provide a pre-compiled version. You can find the appropriate version in the Docs/ directory of the tarball (called gnapplet.sis).

You can install the SIS file in the same way as another symbian application. You can transfer it to the phone over the OBEX protocol (OBEX is available over IrDA or Bluetooth).

You can use the following settings in your gnokiirc to access the phone:

  • Bluetooth connection
        [global]
        port = _bluetooth_address_
        rfcomm_channel = 14
        model = gnapplet
        connection = bluetooth
    
  • IrDA connection
        [global]
        port = /dev/ircomm0
        model = gnapplet
        connection = irda
    

You have to start gnapplet first (you'll find it in the menu), then start gnokii or xgnokii. After gnokii disconnects (or you won't connect in 30 seconds), the application will terminate.

The current code is able to:

  • identify the phone
  • read/write/delete phonebook entries
  • read/delete call log (missed, received, dialled calls)
  • read the memory status
  • read network info
  • read RF/battery level

Bugs

Symbian Series60 3rd Edition phones are not compatible with gnapplet.

Symbian Series80 phones are not compatible with gnapplet.

Phonebook handling is quite limited:

  • name isn't set or read correctly
  • missing attributes
  • no group handling
  • missing SIM memory handling

Mac OS X support

Status

The MacOS X port of Gnokii has successfully been tested on some phones. I expect all phones supported by gnokii to work (famous last words...)

XGnokii, and others

The graphical X version, the AT-emulater and virtual device are not ported to MacOS X. This might change in the future but as far as I know no work is in progress. Of course the effort of porting only makes sense if there is a need. Do you have the need for extended MacOS X functionality don't ask me but let us all know on the Gnokii mailing list.

Successfully tested hardware

USB to Serial adapters

  • Keyspan USA-28Xb
  • BAFO technologies BF-810

Cables

  • dlr3p

Phones

  • 3410
  • 6210
  • 6310

IrDA

The MacOS X version *does not* work with IrDA (and probably never will). This is not a problem of Gnokii but a problem with Apple. The MacOS X IrDA protocol stack is completely undocumented thus unusable. Unless they change this or someone ports the IrDA stack from linux we're out of luck, sorry.

Contents of my .gnokiirc file:

port = /dev/cu.USA28X21P1.1
model = 6210
initlength = default
connection = dlr3p
#require_dcd = 1
use_locking = no

Always set "use_locking = no" otherwise gnokii won't work. USB to serial adapters always introduce two new device files in /dev per serial port. Use the one starting with "cu.".

Compiling

This was only tested under 10.2. May not work with older versions. The base directory of gnokii will be called <gnokii_dir>.

  1. get and install fink. Apart from the base package (= the installer) nothing is needed.
  2. copy the contents of /sw/share/aclocal to /usr/share/aclocal. You need to be root to do this
  3. call 'cd <gnokii_dir>'
  4. call 'sh autogen.sh --disable-shared --disable-nls'
  5. call 'make'

If after some time you now see

"##########################################
 ###
 ### It is strongly recommended to run:
 ### make install
 ### now. Otherwise gnokii may not work.
 ###
 ##########################################"
gnokii should be built OK

Windows support

The graphical X version, the AT-emulator and virtual device are not ported to Win32. This might change in the future but as far as I know no work is in progress. Of course the effort of porting only makes sense if there is a need. Do you have the need for extended Win32 functionality don't ask me but let us all know on the Gnokii mailing list.

Compile using Microsoft Visual C++

Below a description how to compile Gnokii with the Microsoft Visual C++ 6.0.

  1. Put the Gnokii source in <path&tgt;\gnokii\gnokii src.
  2. Copy <path>\win32\MSVC6\config.h into <path>\include\
  3. Open <path>\win32\MSVC6\gnokii.dsw and compile :)

You may want to change the compiler run-time library settings to singe threaded / debug single threaded to have much smaller binaries.

Compile with Cygwin (B20)

This is in fact the easiest option. Because Cygwin implements a GNU (Unix style) environment on your PC you can almost compile Gnokii 'as is' out of the box.

There are just a few steps extra needed to tweak the Makefile. Read the comments in the Makefile. Actually you might want to keep the '-s' in the LDFLAGS since this strips debug information and keeps your executable lean.

Cross compiling with MinGW

You can easily cross compile gnokii with MinGW, just follow these instructions:

  1. run autoheader
  2. edit win32/mingw-cross/mingw-cross.sh according to your MinGW setup
  3. run make DESTDIR=/tmp/foo to install

IrDA support for Windows

Gnokii does support IrDA connection on Windows system. Due to license issues we cannot distribute all needed files to build Windows support out of the box. Here are the steps you need to take to build IrDA support for Windows.

  1. Get a copy of af_irda.h header file. It is distributed with the Windows IrDA DDK. The contents of the file you can find at: http://www.cswl.com/whiteppr/white/arhead.html
  2. Copy it to some system path
  3. Enable IrDA support in config.h file (see above) by replacing a line:
    #undef HAVE_IRDA
    
    with
    #define HAVE_IRDA 1
    
  4. Build gnokii as described above

Copyright (c) 2001-2011 gnokii project
Last modified Saturday, 30-Jun-2007 15:24:31 MDT