Prepaid-manager-applet (ppm) is an applet for the GNOME Desktop that allows you to check and top up the balance of GSM mobile prepaid SIM cards.

  1. Features
  2. Source Code
  3. Releases
  4. Building
  5. Dependencies
  6. Running
  7. Provider Information
  8. Screenshots and Video
  9. Todo
  10. Tested Hardware
  11. Other tools supporting USSD
  12. Authors
  13. License

Ppm is currently beta quality software.

Prepaid SIM cards are a cheap way to get internet access when traveling abroad. However you need to check and top up your balance from time to time. Most carriers allow to do this via Unstructured Supplementary Service Data (USSD) messages.

If you have the prepaid SIM in your laptop, netbook or in an USB GSM/3G stick you would need to take out the SIM card, stick it into a mobile phone and enter the correct USSD sequence to check or top up the balance (or you would need to use the Windows only software supplied by your provider). With ppm you can do this straight from your laptop without removing the card under Linux.

It uses ModemManager (the GSM and 3G helper of NetworkManager) to talk to the modem and mobile-broadband-provider-info to determine the necessary USSD codes for your provider.

USSD messages are not standardized and vary between providers. They usually look like

*130#

to query the balance and

*123*123456789012#

to top up the balance. The 12 digit number after the second star is the top-up code which can usually be bought in e.g. supermarkets or from your provider to top-up a certain amount of credit.

Features

  • It can check the remaining balance via USSD
  • It can top up the balance with a given code via USSD

Source Code

The source code is available via:

git clone https://git.sigxcpu.org/cgit/ppm

and can be browsed here.

Releases

Tarball releases are available from here, Debian packages are also available.

Building

Fetch the source code from git then do a:

./autogen.sh
make
make install

Dependencies

Running ppm is a bit tricky at the moment since you need git versions of ModemManager. Once these things end up in your favorite distro things will get much easier. You need:

  • ModemManager git, the 0.5 release contains the necessary USSD support. The version in Debian unstable is recent enough.
  • mobile-broadband-provider-info with support for top-up information. The version in Debian Wheezy (>= 20110424) is recent enough.
  • python 2.6 or 2.7
  • PyGI >= 2.28.3, Debian package: python-gobject
  • GTK+ >= 3.0.0, Debian package: libgtk+-3-0

Running

The GNOME wiki explains how to run and debug ModeManager from the command line.

To run ppm and point it to a current mobile-broadband-provider-info database use:

PPM_PROVIDER_DB=/path/to//mobile-broadband-provider-info/serviceproviders.xml /usr/local/bin/prepaid-manager-applet

In case ppm can't determine your provider from the information on the SIM card it will allow you to select a provider from the list.

Provider Information

If the information about your mobile broadband provider is incomplete ppm will complain. In order to complete this information just get the mobile-broadband-info-provider source as described above, look for your provider in the serviceproviders.xml. Search for your provider in the file and add the balance-check and balance-top-up information, e.g.:

 <balance-check>
     <ussd>*130#</ussd>
 </balance-check>
 <balance-top-up>
     <ussd replacement="CODE">*130*CODE#</ussd>
 </balance-top-up>

Then check if the XML is still valid via:

xmllint --noout --dtdvalid file://$PWD/serviceproviders.2.dtd serviceproviders.xml

and send me the patch. More details about the format and how to add other items are in the GNOME Wiki.

Screenshots and Video

Here are screenshots of the balance check and top up dialogs:

balance check dialog balance top up dialog

In this case the messages returned from the provider are in German. This is because USSD messages are free text and the provider doesn't localise things.

This video shows ppm in action:

Todo

For a list of TODOs see the TODO file in the source code

Tested Hardware

The following GSM/3G modems were tested with the listed prepaid providers:

Modem Provider Connection Works Comment
Nokia N900 Swisscom USB yes
Nokia N900 m:tel USB yes Needs mobile-broadband-provider-info git for BiH
Nokia N900 Tchibo Mobil USB yes
Nokia 3120 Swisscom Bluetooth yes BT connection via rfcomm
Huawei E1750 Tchibo Mobil USB yes Needs ModemManager >= 0.5
Huawei E1690 Aldi USB maybe Needs ModemManager >= 0.5
Huawei E1820 USB yes Needs ModemManager >= 0.5
ZTE MF190 O2 USB yes Needs ModemManager >= 0.5

Other tools supporting USSD

These tools support sending USSD messages but don't use any provider info:

Authors

prepaid-manager-applet was written by Guido Günther <agx@sigxcpu.org>.

License

ppm is free software and licensed under the GPL Version 3.