Home · All Classes · Grouped Classes · Annotated · Functions

Network Services

Introduction

Qtopia Network Services are defined by files that allow the configuration of Linux system networking services. Once the Network Service is defined the user customizes and starts the Network Service they require via using the Internet Settings application.

How it Works

Network configuration file format

Qtopia's network support can be configured via Network configuration files in $HOME/Applications/Network/config. The structure and type of these configuration files determines the type of the network.

The following keys are generic to all network types:

The QtopiaNetworkInterface class defines the general interface for plug-ins. The following plug-ins are provided by Qtopia:

  1. Dialup - allows the creation and configuration of network interfaces which require pppd
  2. (W)LAN - allows the creation and configuration of Ethernet and WLAN interfaces
  3. Bluetooth DUN - allows the creation and configuration of ppp connections to devices which support Bluetooth Dialup Networking.

Distribution specific configuration

Unfortunately there is no common way how Linux distributions handle the configuration of network devices. To accomodate for this case Qtopia's network configuration is split into two parts. Each network plug-in handles the generation of configuration parameters and then passes the information on to a network script called <type>-network. This script must be implementated by device integrators in order to enable Qtopia to write its configuration to device specific configuration files. By default, Qtopia provides network script for busybox and SuSE v9.3 systems. If none of the provided scripts is suitable for the target device the template scripts in the plug-in directories can be used as a starting point for new scripts.

The network scripts need root permissions. If Qtopia is started without root permissions a combination of sudo and setuid bit must be used.

The Dialup Plug-in

General dial-up configuration

The Dialup plug-in:

The Dialup plug-in makes use of keys in the Network Service configuration file. For further information refer to pppd documentation or the pppd man page.

In addition to the network configuration file each dial-up interface is associated with a couple of files which guide the dial-up process or give reports about the state of the connection.

GPRS

Introduction

General Packet Radio Service (GPRS) is a GSM data transmission technique that transmits and receives data in packets rather than via a continuous channel.

Qtopia uses the Dialup network plug-in to establishing a connection see : $QPEDIR/src/plugins/networking/dialing/

In the ideal case

GPRS startup procedure

An outline of the mechanism to establish a GPRS connection is provided in the following section. It is assumed that the application Setting->Internet has been used to create a valid GPRS configuration. The following code walkthrough applies to connections which are established via the internal phone modem only. Any other type of serial connection (e.g. via PCMCIA modem cards) does not use the Qtopia phone library and hence uses a slightly different approach.

For detailed description of pppd, please refer to man pppd.

GPRS AT dial string

By default the Dialup plug-in uses the following minimal dial string for GPRS connections:

        dialstring = "AT+CGDCONT=1,\"IP\",\"" + <provider APN> + "\"" + " OK "
               "AT+CGATT=1 OK "
               "OK ATD*99***1#";

This string is not necessarily suitable for all modems. If a GPRS data connection cannot be started this string has to be adjusted to the requirements of the particular modem. It may be necessary to contact the modem manufacturer to determine the dial string that should be used. The dialstring can be customized in $QPEDIR/src/plugins/network/dialing/dialstring.cpp.

PPP network script

The dial-up plug-in uses the system dependent configuration script ppp-network. This script must be provided by system integrators. Whenever the dial-up plug-in requests a system dependent operation it calls ppp-network. It must support the following interface/command line options in order to allow interaction with Qtopia:

The LAN Plug-in

General LAN configuration

The LAN plug-in:

If wireless support is not required the define NO_WIRELESS_LAN can be used to exclude the feature (see Hardware Configuration).

The (W)LAN plug-in makes use of the following keys in the Network Service configuration file. Please note that these entries are stored using QSettings' read/write array support (QSettings::beginReadArray()).

In addition to these fields the WirelessNetworks group can contain the following entries which are the same for all wireless networks. There main purpose is to determine the roaming behavior.

(W)LAN network script

The lan plug-in uses the system dependent network script lan-network. This script must be provided by system integrators. Whenever the lan plug-in requests a system dependent operation it calls ppp-network. It must support the following interface/command line options in order to allow interaction with Qtopia:

The Bluetooth Dial-up Plug-in

General DUN configuration

The Bluetooth dial-up plug-in:

Note that this plug-in only provides the client side of Bluetooth dial-up network. Qtopia's Bluetooth dial-up networking server is provides by a separate server task.

Bluetooth dial-up network script

The Bluetooth dial-up network script is called btdun-network and is almost identical to the dialup network script.

The Proxies page

The Dialup and LAN plug-ins share a proxies page. The settings for this page are defined in the configuration as:

Connectivity state of the device

Applications which are interested in the state of network interfaces should use QtopiaNetwork::online(). If more detailed information are required an application can use the QNetworkState or QNetworkDevice classes.

In order to integrate new plugins into the QNetworkState/QNetworkDevice monitoring system a few requirements must be fulfilled. Each interface must post its state transitions into the network value space. The network value space for a plugin can be found under /Network/Interfaces/<ident>. <ident> is the hash value of the interface handle associated with the particular instance of the plugin. The following entries must be published by the plugin:

WAP

Qtopia stores WAP settings in $HOME/Applications/Network/wap. Every WAP related application must use these configuration settings. They have several groups, with the following keys:

The QWapAccount class may be used as an alternative to directly reading the configuration files.

OTA configuration

Qtopia can handle OTA network configuration messages. These messages contain details like WAP/MMS server and login details. Every received message is handled by the Internet Settings application and will eventually be stored as a WAP/Internet configuration file.

Session management

The Qtopia network server provides a session manager. This is used to ensure that a network interface is shutdown when there is no need for it. If an application starts a network interface the interface will remain active for the life time of the application. This means that network interfaces are stopped if an application crashes or quits. If two applications were to request the same interface the interface will stay active until the last application closes.

To cater for more flexibility the network server can extend the session life time beyond the life time of applications. By default every interface which has been started manually will remain active until it is turned off by the user or the interface times out (e.g. timeout on pppd sessions).

Troubleshooting

Example connect,disconnect scripts

The dial-up process uses chat files. These chat files may need some customization in order to work flawless with particular modems. The chat files are stored in $HOME/Applications/Network/chat. Each interface has a connect and a disconnect chat file. The following two chat files represent rather generic chat files for a GPRS connection.

Enabling Debugging

In order to activate Qtopia's internal network logging facilities you may have to edit $QPEDIR/etc/default/Trolltech/Log.conf or $HOME/Settings/Trolltech/Log.conf. For network debugging you may enable Network and AtChat logging.

Changing the GPRS Packet Size to Compensate for Poor Signal Quality

By default a packet size of 1500 will be used by pppd for GPRS traffic. In cases of poor signal quality it may be necessary to decrease the "mru" and "mtu" packet size being used by pppd, to for 512. See the pppd man page for details on setting mru and mtu values.

Configuration file elements to check/update

  1. check that /etc/ppp/options does not have papcrypt enabled
  2. check the password that may be specified : see /etc/ppp/chap-secrets and /etc/ppp/pap-secrets
  3. check the contents of $HOME/Applications/Network/modules/DialUpGPRS*.conf
  4. check the contents of /etc/ppp/peers/*GPRS*
  5. check that GPRSDialString() in $QPEDIR/src/plugins/networking/dialing/dialstring.cpp suits your modem. For example you may need to use either
    1. AT+CGDCONT=1,"IP" ...
    2. AT+CGDCONT=1,"PPP" ...
  6. update the /etc/ppp/options file to enable debugging and record ALL traffic. eg add
        debug
        record /tmp/ppp-all-text.log
  7. modify the connect-chat, disconnect-chat and startpppd.sh to suit your modem and internet provider : at least

Dialing with the example GPRS Dial script

  1. Ensure that Qtopia and pppd are not running
  2. Start pppd via running startpppd.sh
  3. Ping an non-local address : eg
        ping 216.239.39.99
  4. Confirm that pppd attempts to start the link and review the content of /tmp/ppp-all-text.log
  5. If needed send the recorded traffic as setup in step 2 in a tar.gz to support

Network testing

The following can help to isolate any GPRS issues.

Run the following commands to ping local and non-local resources:

         ping <some IP address on your local network>

         ping 66.102.7.99

         ping <some host on your local network>

         ping www.google.com

It might be necessary to specify the network interface that the ping command should use. If you have more than one network interface and suspect routing issues use:

         ping -I <iface-name> <host>

If one or less of the above tests fail then provide the output of the following commands :

         /sbin/ifconfig -a

         /sbin/ifstatus eth0

         /sbin/route

         cat /etc/resolv.conf

         cat /etc/ppp/resolv.conf

If you have a firewall in use, check that the route uses the correct gateway address and that the firewall is not blocking IP traffic from the device. Lastly it may helpful to compare the results of running the above commands with results given by running the same commands on a development machine.

Requesting Support

If support is needed please ensure that your support request contains the following items:

  1. the peer file ( see /etc/ppp/peers )
  2. the network configuration file ( $HOME/Applications/Network/config/GPRS<peerID>.conf )
  3. the pppd log file ( /tmp/qtopia-0/qpe-pppd-log-<peerID> )
  4. the connect and disconnect chat ( $HOME/Applications/Network/chat/connect-<peerID> )
  5. all parameters passed to pppd (check debug output for network details). Note that network logging may have to be enabled.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3