NAME
gsmctl, gsmsiectl - GSM mobile phone control program
SYNOPSIS
gsmctl [-b baudrate] [--baudrate baudrate] [-d device] [--device
device] [-h] [--help] [-I init string] [--init init string] [-v]
[--version] [-X] [--xonxoff] -o operation | --operation operation |
parameters
gsmsiectl [-b baudrate] [--baudrate baudrate] [-d device] [--device
device] [-h] [--help] [-I init string] [--init init string] [-v]
[--version] [-X] [--xonxoff] -o operation | --operation operation |
parameters
DESCRIPTION
gsmctl can request information from or perform operations on an GSM
mobile phone.
gsmctl attaches itself to the device given on the command line (usually
an GSM modem) using the specified baudrate. If no device is given, the
device /dev/mobilephone is used. If no baudrate is given, a default
baud rate of 38400 is used.
gsmctl can be used in to modes: If no --operation option is given the
parameters specify the status information to be retrieved from the
mobile phone. See the section STATUS INFORMATION for more details. If
an --operation option is given the requested operation is performed on
the mobile using the parameters. See the section OPERATIONS for more
details.
gsmsiectl is the same program with some extension for Siemens mobile
phones. Some extra OPERATIONS are available in this case.
Error messages are printed to the standard error output. If the
program terminates on error the error code 1 is returned.
OPTIONS
-b baudrate, --baudrate baudrate
The baud rate to use. Defaults to 38400.
-d device, --device device
The device to which the GSM modem is connected. The default is
/dev/mobilephone.
-h, --help
Prints an option summary.
-I init string, --init init string
Initialization string to send to the TA (default: "E0"). Note
that the sequence "ATZ" is sent first.
-o operation, --operation operation
This option is used to perform an operation on the mobile phone.
Refer to the section OPERATIONS for more information on the
available operations and the parameters required for each
operation.
-v, --version
Prints the program version.
-X, --xonxoff
Uses software handshaking (XON/XOFF) for accessing the device.
STATUS INFORMATION
If called without the --operation option gsmctl prints out default
mobile phone status information as specified by the parameters
described below:
ALL Prints all available information.
BATT Prints out information about the current battery status. Two
lines of the form "<BATT0> text" and "<BATT1> charge" are
printed. Text may be of "0 ME is powered by the battery", "1 ME
has a battery connected, but is not powered by it", "2 ME does
not have a battery connected", or "3 Recognized power fault,
calls inhibited". Charge is a number in the range 0..100 where 0
means that the battery is empty or not connected and 100 means
full charge.
BITERR Prints information about the current bit error rate. The output
is of form "<BITERR0> value" where value can be of 0..7, 99 (99
means not available or not detectable).
CLIP This option prints a line of the form "<CLIP0> on" if caller
line identification is turned on in the network, "<CLIP0> off"
otherwise.
CSET Display info about charsets. The output is in the form "<CSET0>
available" and "<CSET1> current", which describes the charsets
available and which is current.
CURROP Prints information about the current operator. The output line
has the form "<CURROP0> Long name: ´xxxx´ Short name: ´yyyy´
Numeric Name: zzzz".
FLCAP Prints out the two-letter names of available facility locks. The
meaning of standardized facility lock names is as follows:
CS Lock control surface (eg. phone keyboard)
PS Lock phone to SIM card (mobile phone asks password when other
than current SIM card inserted)
SC Lock SIM card (SIM asks password in mobile phone power-up and
when this lock command issued)
AO Barr all outgoing calls
OI Barr outgoing international calls
OX Barr outgoing international calls except to home country
AI Barr all incoming calls
IR Barr incoming calls when roaming outside the home country
NT Barr incoming calls from numbers not stored to TA memory
NM Barr incoming calls from numbers not stored to mobile phone
memory
NS Barr incoming calls from numbers not stored to SIM memory
NA Barr incoming calls from numbers not stored in Any memory
AB All Barring services (FIXME)
AG All outGoing barring services (FIXME)
AC All inComing barring services (FIXME)
FD SIM fixed dialling memory feature (if PIN2 authentication has
not been done during the current session, PIN2 is required as
<passwd>)
Note that mobile phones may implement facility locks not
documented here.
FLSTAT Prints information about the status of facility locking in the
mobile phone. For each facility a line of the form "<FLSTATn>
´facilityname´ classes" is printed. The classes may be "Voice",
"Data", and/or "Fax" depending on the class for which the
facility is enabled. If "unknown" is printed out this means that
the TA is not able to report the status. If the facility is not
enabled for any class, no class identifier is printed. See FLCAP
for information about the available two-letter names of facility
locks.
FORW Prints information about call forwarding enabled in the mobile
phone. For each combination of reason (UnconditionalReason,
MobileBusyReason, NoReplyReason, and NotReachableReason) and
class (Voice, Data, and Fax) a line of the form "<FORWn.m>
reason class number: xxx subaddr: yyy time: zzz" is printed. The
time is the number of seconds to wait before forwarding in case
of NoReplyReason.
ME Prints manufacturer, model, revision, and serial number of the
mobile phone (ME = mobile equipment). Output lines are numbered
from "<ME0>" to "<ME3>".
OP Prints information about the currently available mobile network
operators. For each operator an output line of the form "<OPn>
status Long name: ´xxxx´ Short name: ´yyyy´ Numeric name: zzz"
is returned where status may be of:
unknown The status of the operator is unknown.
current This is the currently selected operator.
available This operator is available for selection.
forbidden This operator is not available for selection, ie. not
accessible with this SIM card.
PIN Prints information about the current PIN status. The output is
of form "<PIN0> status". Where status can be one of the
following lines:
READY ME is not pending for any password.
SIM PIN ME is waiting SIM PIN to be given.
SIM PUK ME is waiting SIM PUK to be given.
PH-SIM PIN
ME is waiting phone/-to/-SIM card password to be
given.
PH/-FSIM PIN
ME is waiting phone/-to/-very first SIM card password
to be given.
PH/-FSIM PUK
ME is waiting phone/-to/-very first SIM card
unblocking password to be given.
SIM PIN2 ME is waiting SIM PIN2 to be given.
SIM PUK2 ME is waiting SIM PUK2 to be given.
PH/-NET PIN
ME is waiting network personalisation password to be
given.
PH/-NET PUK
ME is waiting network personalisation unblocking
password to be given.
PH/-NETSUB PIN
ME is waiting network subset personalisation password
to be given.
PW Facilities in the mobile phone may be protected by passwords
(ie. PINs or PUKs). This option prints out lines of the form
"<PWn> ´facilityname´ len" for each facility for which a
facility lock password exists. See FLCAP for information about
the available two-letter names of facility locks.
SCA Reports the default SMS service centre address currently set in
the mobile phone.
SIG Prints information about the current network signal strength.
The output is of the form "<SIG0> value". Following values are
possible:
0 -113 dBm or less
1 -111 dBm
2...30 -109... -53 dBm (in steps of 2 dBm)
31 -51 dBm or greater
99 not known or not detectable
OPERATIONS
dial number
Dials number. After dialling gsmctl waits for a <CR> keypress
to terminate.
forw mode reason number [facilityclass] [forwardtime]
Changes the call forwarding behaviour in the network. mode can
be any of:
disable Call forwarding is disabled.
enable Call forwarding is enabled. The call forwarding
reason, number, and (optionally) forwardtime must be
registered beforehand.
register This registers the call forwarding reason, number,
and forwardtime in the network.
erase This is the counterpart to register. It erase the call
forwarding info in the network.
reason can be any of:
unconditional This applies to every call.
mobilebusy The mobile phone is busy.
noreply The call is not answered in forwardtime seconds.
notreachable Mobile phone cannot be reached (ie. switched
off).
all This refers to all forwarding reasons.
allconditional This refers to all conditional forward reasons
(mobilebusy, noreply, notreachable).
number is the number the incoming call is forwarded to. See the
explanation for lock operation for the meaning of facilityclass.
The default for forwardtime is 20 seconds if omitted.
forwardtime can be in the range 1..30.
off Sets functionality level of the phone to 0 (low functionality).
The effects of this command depend on the phone (eg. sets low
power consumption).
on Sets functionality level of the phone to 1 (high functionality).
The effects of this command depend on the phone.
pin pin
Sets PIN code. Use gsmctl pin to get the current pin status.
lock facility [facilityclass] [passwd]
Locks the named facility. Use gsmctl flcap to get a list of
supported facilities. The facilityclass can be any of:
all Voice, data, and fax.
v vf vd f fd d Any combination of voice, data and fax.
The default is all if facilityclass is omitted. The passwd is
password for the facility. If no password is given this
parameter can be omitted.
setop opmode numericname
Sets the current operator to numericname. Use gsmctl op to get
a list of operators with their numeric codes. opmode can be any
of:
automatic
manual
deregister Deregister from network.
manualautomatic If manual selection fails, automatic mode is
entered.
setpw facility [oldpasswd] [newpasswd]
Sets the password for the facility. If one of the passwords is
omitted this means that the facility has no password protection.
Passwords are PIN1, PIN2, PUK etc.
setsca service centre address
Sets the default SMS service centre address.
unlock facility [facilityclass] [passwd]
This is the reverse operation to lock. See above for a
description of the parameters.
Extra operators for gsmsiectl:
cset
Charset info.
pbook
Phone book info.
signal
Signal tone info.
ring
Ringing tone info.
binary
Binary info.
EXAMPLES
The following invocation of gsmctl prints out all available status
information for the mobile phone connected to /dev/mobilephone
gsmctl all
The output could look like (lines edited to fit):
<ME0> Manufacturer: SIEMENS
<ME1> Model: S10
<ME2> Revision: 06
<ME3> Serial Number: 448058511817585
<OP0> Status: available Long name: ’D1/-TELEKOM’ Short name: ’’
Numeric name: 26201
<OP1> Status: forbidden Long name: ’D2 PRIVAT’ Short name: ’’
Numeric name: 26202
<CURROP0> Long name: ’D1/-TELEKOM’ Short name: ’’ Numeric name:
26201 Mode: automatic
<FLSTAT0> ’CS’
<FLSTAT1> ’PS’
<FLSTAT2> ’SC’ Voice Data Fax
<FLSTAT3> ’AO’
<FLSTAT4> ’OI’
<FLSTAT5> ’OX’
<FLSTAT6> ’AI’
<FLSTAT7> ’IR’
<FLCAP0> ’CS’ ’PS’ ’SC’ ’AO’ ’OI’ ’OX’ ’AI’ ’IR’ ’AB’ ’AG’ ’AC’
<PW0> ’PS’ 8
<PW1> ’SC’ 8
<PW2> ’AO’ 4
<PW3> ’OI’ 4
<PW4> ’OX’ 4
<PW5> ’AI’ 4
<PW6> ’IR’ 4
<PW7> ’AB’ 4
<PW8> ’AG’ 4
<PW9> ’AC’ 4
<CLIP0> on
<FORW0.0> UnconditionalReason Voice inactive number: subaddr:
time: -1
<FORW0.1> UnconditionalReason Data inactive number: subaddr:
time: -1
<FORW0.2> UnconditionalReason Fax inactive number: subaddr:
time: -1
<FORW1.0> MobileBusyReason Voice active number: +494012345678
subaddr: time: -1
<FORW1.1> MobileBusyReason Data inactive number: subaddr:
time: -1
<FORW1.2> MobileBusyReason Fax inactive number: subaddr: time:
-1
<FORW2.0> NoReplyReason Voice active number: +494012345678
subaddr: time: 20
<FORW2.1> NoReplyReason Data inactive number: subaddr: time:
-1
<FORW2.2> NoReplyReason Fax inactive number: subaddr: time: -1
<FORW3.0> NotReachableReason Voice active number: +494012345678
subaddr: time: -1
<FORW3.1> NotReachableReason Data inactive number: subaddr:
time: -1
<FORW3.2> NotReachableReason Fax inactive number: subaddr:
time: -1
<BATT0> 0 ME is powered by the battery
<BATT1> 100
<BITERR0> 0
<SIG0> 19
The following locks the keys on the mobile phone:
gsmctl -o lock cs
This changes the SIM card PIN from 1234 to 2345:
gsmctl -o setpw sc 1234 2345
Switch off all call forwarding (actually erase the numbers):
gsmctl -o forw erase all
Switch on call forwarding to German D1 voice box:
gsmctl -o forw register notreachable 3313
gsmctl -o forw enable notreachable
FILES
/dev/mobilephone
Default mobile phone device.
AUTHOR
Peter Hofmann <software@pxh.de>
BUGS
Report bugs to software@pxh.de. Include a complete, self-ncontained
example that will allow the bug to be reproduced, and say which version
of gsmctl you are using.
COPYRIGHT
Copyright © 1999 Peter Hofmann
gsmctl is free software; you can redistribute it and/or modify it under
the terms of the GNU Library General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.
gsmctl is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
License for more details.
You should have received a copy of the GNU Library General Public
License along with gsmctl; see the file COPYING. If not, write to the
Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
SEE ALSO
gsminfo(7), gsmpb(1), gsmsendsms(1), gsmsmsd(8), gsmsmsstore(1).