gsm-ussd man page

gsm-ussd — Send USSD queries by GSM/UMTS modem

Synopsys

gsm-ussd --help|-h|-?
gsm-ussd [-m <modem>] [-t <timeout>] [-p <pin>] [-d] [-l <logfile>] [<ussd-cmd>...]
gsm-ussd [-m <modem>] [-t <timeout>] [-d] [-l <logfile>] --cancel|-c

Description

This script sends a USSD query to a modem, waits for the answer and displays it. The modem type is detected and any necessary en-/decoding and error checking is done.

Options

--modem|-m <modem>
Sets the device file to use to connect to the modem. Default is "/dev/ttyUSB1".

Please note: Depending on your modem's make and model, you might get more than one serial USB interfaces when connecting the modem! For example, the Huawei E160 gets two: "/dev/ttyUSB0" and "/dev/ttyUSB1". The first is for data, commands and state messages use the second port.
--timeout|-t <timeout_in_secs>
The timeout in seconds that the script will wait for an answer after each command sent to the modem. Default is 20 seconds.
--pin|-p <PIN>
The SIM PIN to use if the card is still locked. This is typically the case just after the modem got stuck into your computer. Attention: The SIM PIN can be seen in the process list as long as the script is running - use with care on multi user systems! Attention again: If you are using a shell with a command line history, your SIM PIN will be stored there for a while in clear.
--cleartext|-c
This option causes gsm-ussd to send USSD queries in cleartext, i.e. without encoding them into a 7bit-packed-hex-string, as is needed for Huaweis E160* series of UMTS modems. This takes precedence before any detected modem type.
--no-cleartext
This is the opposite of the previous option: Use encoding, even if the modem type does not indicate that it is needed. This (obviously) takes precedence before any detected modem type.
--cancel|-c
Aborts an active USSD session. USSD sessions are queries for more information by the provider; they can take the form of simple menus with numbers to choose the menu entries or a query to enter a top up code.
--help|-h|-?
Shows the online help.

The following options aren't meant for everyday usage, but as diagnostic aids in development or for the pathologically curious. Please be reminded again that any logs or debugging output will show your PIN if you're using option "--pin <PIN>"! So use with care.

--logfile|-l <logfilename>
Writes the chat between modem and script into the named log file. Useful to look for unexpected modem answers (or expected modem answers that nevertheless weren't handled correctly). Clearly more a debugging help than anything else.
--debug|-d
Switches debug mode on. The script will then explain its actions and their results in high detail.

Arguments

A USSD query is a "phone number" starting with "*" and ending with "#" which let's you do interesting things in a GSM network. By default, if you don't specify any USSD query, "*100#" will be used, which causes all GSM network providers known to me to provide the balance of your prepaid account.

If you enter more than one USSD query, they will be sent in order and the result of each on its own line.

Please note: USSD queries are different for each provider!

List of interesting things:

·

German Telecom/D1 (congstar)

·
*100#

Show prepaid account balance.
·
*101*cashcode#

Top up your prepaid account with a "Cashcode" (top up code). Please note that a cash code consists only of numbers! Dashes in your cash code are simply used for readability, don't enter them. Use only the numbers.
·
*135#

Displays your own phone number.
·

Vodafone/D2

·
*100#

Show prepaid account balance.
·
*102#

Displays costs of your last connection.
·

O2 (Tchibo, FONIC, ...)

·
*100#

O2/Tchibo-Mobile: A menu with further options. This will start an USSD session.
·
*101#

Show prepaid account balance.
·
*102#

Prepaid account validity.
·
*103*topupcode#

Topping up your prepaid account. Please note that a top up code consists of numbers only! Dashes in your top up code are simply used for readability - don't enter them. Use only the numbers.

Sending '*103#' without a top up code will start a USSD session asking for the code.
·

E-Plus & Resellers

·
*100#

Show prepaid account balance.
·
*104*cashcode#

Top up your prepaid account with a "Cashcode" (top up code). Please note that a cash code consists only of numbers! Dashes in your cash code are simply used for readability, don't enter them. Use only the numbers.

This works for the E-Plus net, not only for the E-Plus provider. So you can use this USSD query for E-Plus resellers (AldiTalk, Simyo, Blue, ...) too.

Exit Code Values

"gsm-ussd(1)" sets its exit code as follows:

·
0 - Successful USSD query
·
1 - SIM is locked, PIN needed
·
2 - Wrong PIN given, SIM still locked
·
3 - No net registration
·
4 - Error ocurred (Timeouts etc.)
·
10 - Bug in program. This exit code should never be seen.

Author

Jochen Gruse, <mailto:jochen@zum-quadrat.de>

Info

2016-05-15 perl v5.24.0 User Contributed Perl Documentation