- G N O K I I - (C) Hugh Blemings, hugh@vsb.com.au 1999 Last update 5 March 1999 Version 0.2.3 - Introduction - This is version 0.2.3 of gnokii, a Linux/Unix tool suite and (eventually) modem/fax driver for Nokia mobile phones, released under the GPL. Please see COPYING for more details on license/copying issues. At present only 3110, 3810 and 8110 phones with the DAU-4F cable have been tested. Other cables, including home made ones will very likely work. Details of other handsets and networks are provided below. This version of the software has had a number of changes made to the source code to allow support for other phones to be readily incorporated. The files fbus-6110.c and fbus-6110.h are provided as a starting point for work on supporting this range of phones. A group are presently working on providing this support, their efforts will be incorporated into gnokii in the not to distant future. The code supplied is still relatively new and hence has had limited testing. Bugs where know are detailed in the file BUGS... Play around with it, hack at it and see what you discover but please do so in the knowledge that it comes with no warranty or guarantee - you use it at your own risk. The resulting executable allows you to read/write phonebook entries, send SMS messages to the network, dump SMS messages from the phone and enter a monitor mode to look at the protocol and any unknown messages that may occur. The latter are printed in hexadecimal form and are provided to help with understanding of the protocol. 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. 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 something of another matter. 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. 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. - Installation - Review gnokii.c, and make sure that the MODEL and PORT defines are correct for your setup. You'll need r/w permissions on the port you select. If you set MODEL to 6110 you will see lots of "Not implemented" errors unless you've added the corresponding routines to fbus-6110.c! If your SIM card allows names longer than 10 character, modify FB38_DEFAULT_SIM_PHONEBOOK_NAME_LENGTH in fbus-3810.h accordingly. 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. If you are going to use --sendsms, read the notes above as it may not work for you. - Known Bugs - Review the file BUGS in the first instance. If you are using gnokii, particularly in these early days, it is worth joining the mailing list as bugs will be reported there first! Alternatively review the BUGS file on the web site. - How to help - You can assist the development process and by making note of any messages that occur and seeing if you can work out what they mean. 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. Internationalisation is desirable for a program such as gnokii, if you would like to assist in providing translations into other languages please let me know. - 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. Somewhat more of the protocol has been investigated than is presently included in the 3810 section of the software. However, they are not yet fully understood and hence have been left out of the included code for now. - To Do - A lot! :) The software roadmap document on the web site contains information about the proposed future directions for the project. Additionally, these sort of matters are actively discussed on the mailing list. At the present, the user interface, error reporting and such like is hardly what one would call user friendly. This too will improve as the project progresses. Incorporate the GNU gettext Internationalisation library to assist with making gnokii multi lingual. - References - The web site for this project is at; 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 :) - Handsets/Networks tested - 3110/Sonera (Finland) 3810/Telstra (Australia) 3810/Optus [Actually Hutchison] (Australia) 8110/Proximus (Belgium) 8110/D2 Privat (Germany) 8110i/MTN (South Africa) 3810/Mobile One (Singapore) 3810/SingTel Mobile (Singapore) - Credits - Thank you to, in no particular order... * Everyone on the linux-nokia mailing list for their interest and input into the project. * Francois Dessart, Brendan O'Dea, Tony Lindstrom, Steffan Henke and Cobus Van Eeden for dumps (and in some cases interpretation!) of unknown messages, bug reports and prompt feedback of being able to build new releases. * Pavel Janik for spelling corrections and a few code cleanups. * Staffan Ulfberg for taking care of the website and for instigating the 6110 project which has now been merged with the gnokii effort. * Martin Hamilton for looking after the mailing list. * Tim Potter some of the ideas that are now incorporated in gnokii to provide multiple model support. * Lucy for making pizza and putting up with me disappearing to work on this :) - Release Notes - 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 centre 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.