1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
[[!meta title="GNOME Prepaid Manager Applet"]]
[[!meta description="GNOME, prepaid, GSM, UMTS, USSD"]]
Prepaid-manager-applet (ppm) is an applet for the [GNOME][1] Desktop that
allows you to check and top up the balance of GSM mobile prepaid SIM cards.
[[!toc ]]
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][1] (the GSM and 3G helper of [NetworkManager][4]) to
talk to the modem and [mobile-broadband-provider-info][3] 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
[[!template id=honk_git repo="ppm"]]
### Releases
Tarball releases are available from [here](http://honk.sigxcpu.org/projects/ppm/tarballs/),
[Debian][Debian] packages are [also available][10].
### 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][6], the 0.5 release contains the necessary USSD
support. The version in Debian unstable is recent enough.
* [mobile-broadband-provider-info][5] 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][8] 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|/agx]] the patch. More details about the format and how to add other items are in the [GNOME Wiki][9].
### Screenshots and Video
Here are screenshots of the balance check and top up dialogs:
<div class="screenshots">
[[!img check.png size="x150" alt="balance check dialog"]]
[[!img topup.png size="x150" alt="balance top up dialog"]]
</div>
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:
<div class="screenshots">
<video width="550" height="300" controls="controls">
<source src="ppm.webm" type="video/webm" />
Video of GNOME Prepaid Manager
</video>
</div>
### 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:
[[!table class="datatable" data="""
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:
* [ussdq](http://sourceforge.net/projects/ussdq/)
* [wammu](http://wammu.eu/)
* [gsm-ussd](http://freshmeat.net/projects/gsm-ussd)
### 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.
[1]: http://gnome.org
[2]: http://live.gnome.org/NetworkManager/MobileBroadband
[3]: http://live.gnome.org/NetworkManager/MobileBroadband/ServiceProviders
[4]: http://projects.gnome.org/NetworkManager/
[5]: http://git.gnome.org/browse/mobile-broadband-provider-info/
[6]: http://cgit.freedesktop.org/ModemManager/ModemManager/
[8]: http://live.gnome.org/NetworkManager/Debugging
[USSD]: http://en.wikipedia.org/wiki/Unstructured_Supplementary_Service_Data
[9]: http://live.gnome.org/NetworkManager/MobileBroadband/ServiceProviders
[Debian]: http://debian.org
[10]: http://packages.debian.org/sid/prepaid-manager-applet
|
