Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Device::Gsm(3)	      User Contributed Perl Documentation	Device::Gsm(3)

NAME
       Device::Gsm - Perl extension to interface GSM phones / modems

SYNOPSIS
	 use Device::Gsm;

	 my $gsm = new Device::Gsm( port => '/dev/ttyS1', pin => 'xxxx'	);

	 if( $gsm->connect() ) {
	     print "connected!\n";
	 } else	{
	     print "sorry, no connection with gsm phone	on serial port!\n";
	 }

	 # Register to GSM network (you	must supply PIN	number in above	new() call)
	 # See 'assume_registered' in the new()	method documentation
	 $gsm->register();

	 # Send	quickly	a short	text message
	 $gsm->send_sms(
	     recipient => '+3934910203040',
	     content   => 'Hello world!	from Device::Gsm'
	 );

	 # Get list of Device::Gsm::Sms	message	objects
	 # see `examples/read_messages.pl' for all the details
	 my @messages =	$gsm->messages();

DESCRIPTION
       "Device::Gsm" class implements basic GSM	functions, network
       registration and	SMS sending.

       This class supports also	"PDU" mode to send "SMS" messages, and should
       be fairly usable. In the	past, I	have developed and tested it under
       Linux RedHat 7.1	with a 16550 serial port and Siemens C35i/C45 GSM
       phones attached with a Siemens-compatible serial	cable. After some
       years, I	have developed and tested it with Linux	Slackware 10.2 and a
       Cambridge Silicon Radio (CSR) USB bluetooth dongle, connecting to a
       Nokia 6600 phone.

       Currently I don't use this software anymore. It should probably still
       work, but it's unlikely I will ever be able to test it with a real gsm
       module.

       Feel free to contact me if you have any trouble or you are interested
       in improving this software.

       If you need a way to test your gsm module or phone, and you don't mind
       spending	an SMS,	use the	"examples/send_to_cosimo.pl" script to notify
       me that "Device::Gsm" still works and works well	with your device
       (thanks!).

       Over the	years, I have collected	hundreds of messages from all over the
       world :-)

WHY?
       Why would you want to use this?

       When I started writing this software, around year 2000, I needed	a
       practical way to	automatically send tens	of SMS messages	through	my
       phone.

       Fast forward to 2016, I barely use SMS messages anymore,	and you	can
       find plenty of TCP/IP based services to send SMS	messages, maybe	even
       for free.

       The only	motivation left	would be to learn how AT commands work for GSM
       modules.	I had lots of fun learning this, but it	was so many years ago,
       and YMMV, as they say.

METHODS
       The following documents all supported methods with simple examples of
       usage.

   new()
       Inherited from Device::Modem. See Device::Modem documentation for more
       details.

       The only	mandatory argument is the "port" you want to use to connect to
       the GSM device:

	   my $gsm = Device::Gsm->new(
	       port => '/dev/ttyS0',
	   );

       On some phones, you may experience problems in the GSM network
       registration step. For this reasons, you	can pass a special
       "assume_registered" option to have Device::Gsm ignore the registration
       step and	assume the device is already registered	on the GSM network.
       Example:

	   my $gsm = Device::Gsm->new(
	       port => '/dev/ttyS0',
	       assume_registered => 1,
	   );

       If you want to send debugging information to your own log file instead
       of the default setting, you can:

	   my $gsm = Device::Gsm->new(
	       port => '/dev/ttyS1',
	       log => 'file,/tmp/myfile.log',
	       loglevel	=> 'debug',  # default is 'warning'
	   );

   connect()
       This is the main	call that connects to the appropriate device. After
       the connection has been established, you	can start issuing commands.
       The list	of accepted parameters (to be specified	as hash	keys and
       values) is the same of "Device::SerialPort" (or "Win32::SerialPort" on
       Windows platform), as all parameters are	passed to those	classes'
       connect() method.

       The default value for "baudrate"	parameter is 19200.

       Example:

	   my $gsm = Device::Gsm->new( port=>'/dev/ttyS0', log=>'syslog' );
	   # ...
	   if( $gsm->connect(baudrate => 19200)	) {
	       print "Connected!";
	   } else {
	       print "Could not	connect, sorry!";
	   }
	   # ...

   datetime()
       Used to get or set your phone/gsm modem date and	time.

       If called without parameters, it	gets the current phone/gsm date	and
       time in "gsm" format, "YY/MM/DD,HH:MN:SS". For example
       "03/12/15,22:48:59" means December the 15th, at 10:48:59	PM. Example:

	   $datestr = $gsm->datetime();

       If called with parameters, sets the current phone/gsm date and time to
       that of supplied	value. Example:

	   $newdate = $gsm->datetime( time() );

       where "time()" is the perl's builtin "time()" function (see "perldoc -f
       time" for details). Another variant allows one to pass a	"localtime"
       array to	set the	correspondent datetime.	Example:

	   $newdate = $gsm->datetime( localtime() );

       (Note the list context).	Again you can read the details for "localtime"
       function	with "perldoc -f localtime".

       If your device does not support this command, an	undefined value	will
       be returned in either case.

   delete_sms()
       This method deletes a message from your SIM card, given the message
       index number.  Example:

	   $gsm->delete_sms(3);

       An optional second parameter specifies the "storage". It	allows one to
       delete messages from gsm	phone memory or	sim card memory. Example:

	   # Deletes first message from	gsm phone memory
	   $gsm->delete_sms(1, 'ME');

	   # Deletes 3rd message from sim card
	   $gsm->delete_sms(3, 'SM');

       By default, it uses the currently set storage, via the "storage()"
       method.

   forward()
       Sets call forwarding. Accepts three arguments: reason, mode and number.
       Reason can be the string	"unconditional", "busy", "no reply" and
       "unreachable".  Mode can	be the string "disable", "enable", "query",
       "register", "erase".

       Example:

	   # Set unconditional call forwarding to +47 123456789
	   $gsm->forward('unconditional','register','+47123456789');

	   # Erase unconditional call forwarding
	   $gsm->forward('unconditional','erase');

   hangup()
       Hangs up	the phone, terminating the active calls, if any.  This method
       has been	never tested on	real "live" conditions,	but it needs to	be
       specialized for GSM phones, because it relies on	"+HUP" GSM command.
       Example:

	   $gsm->hangup();

   imei()
       Returns the device own IMEI number (International Mobile	Station
       Equipment Identity).

       This identifier is numeric and is supposed to be	unique among all GSM
       mobile devices and phones. Example:

	   my $imei = $gsm->imei();

   manufacturer()
       Returns the device manufacturer,	usually	only the first word (example:
       "Nokia",	"Siemens", "Falcom", ...). Example:

	   my $man_name	= $gsm->manufacturer();
	   if( $man_name eq 'Nokia' ) {
	       print "We have a	nokia phone...";
	   } else {
	       print "We have a	$man_name phone...";
	   }

   messages()
       This method is a	somewhat unstable and subject to change, but for now
       it seems	to work. It is meant to	extract	all text SMS messages stored
       on your SIM card	or gsm phone.  In list context,	it returns a list of
       messages	(or undefined value if no message or errors), every message
       being a "Device::Gsm::Sms" object.

       The only	parameter specifies the	"storage" where	you want to read the
       messages, and can assume	some of	the following values (but check	your
       phone/modem manual for special manufacturer values):

       "ME"
	   Means gsm phone MEmory

       "MT"
	   Means gsm phone MEmory on Nokia phones?

       "SM"
	   Means Sim card Memory (default value)

       Example:

	   my $gsm = Device::Gsm->new();
	   $gsm->connect(port=>'/dev/ttyS0') or	die "Can't connect!";

	   for(	$gsm->messages('SM') )
	   {
	       print $_->sender(), ': ', $_->content(),	"\n";
	   }

   mode()
       Sets the	device GSM command mode. Accepts one parameter to set the new
       mode that can be	the string "text" or "pdu". Example:

	   # Set text mode
	   $gsm->mode('text');

	   # Set pdu mode
	   $gsm->mode('pdu');

   model()
       Returns phone/device model name or number. Example:

	   my $model = $gsm->model();

       For example, for	Siemens	C45, $model holds "C45"; for Nokia 6600,
       $model holds 6600.

   network()
       Returns the current registered or preferred GSM network operator.
       Example:

	   my $net_name	= $gsm->network();
	   # Returns 'Wind Telecom Spa'

	   my($net_name, $net_code) = $gsm->network();
	   # Returns ('Wind Telecom Spa', '222 88')

       This obviously varies depending on country and network operator.	For me
       now, it holds "Wind Telecomunicazioni SpA". It is not guaranteed	that
       the mobile phone	returns	the decoded network name. It can also return a
       gsm network code, like "222 88".	In this	case, an attempt to decode the
       network name is made.

       Be sure to call the "network()" method when already registered to gsm
       network.	See "register()" method.

   signal_quality()
       Returns the measure of signal quality expressed in dBm units, where
       near to zero is better.	An example value is -91	dBm, and reported
       value is	"-91".	Values should range from -113 to -51 dBm, where	-113
       is the minimum signal quality and -51 is	the theoretical	maximum
       quality.

	   my $level = $gsm->signal_quality();

       If signal quality can't be read or your device does not support this
       command,	an undefined value will	be returned.

   software_version()
       Returns the device firmware version, as stored by the manufacturer.
       Example:

	   my $rev = $gsm->software_revision();

       For example, for	my Siemens C45,	$rev holds 06.

   storage()
       Allows to get/set the current sms storage, that is where	the sms
       messages	are saved, either the sim card or gsm phone memory.
       Phones/modems that do not support this feature (implemented by "+CPMS"
       AT command won't	be affected by this method.

	   my @msg;
	   my $storage = $gsm->storage();
	   print "Current storage is $storage\n";

	   # Read all messages on sim card
	   $gsm->storage('SM');
	   @msg	= $gsm->messages();

	   # Read messages from	gsm phone memory
	   $gsm->storage('ME');
	   push	@msg, $gsm->messages();

   test_command()
       This method queries the device to know if a specific AT GSM command is
       supported.  This	is used	only with GSM commands (those with "AT+"
       prefix).	 For example, if I want	to know	if my device supports the
       "AT+GXXX" command:

	   my $gsm = Device::Gsm->new( port => '/dev/myport' );

	   ...

	   if( $gsm->test_command('GXXX') ) {
	       # Ok, command is	supported
	   } else {
	       # Nope, no GXXX command
	   }

       Note that if you	omit the starting "+" character, it is automatically
       added.  You can also test commands like "^SNBR" or the like, without
       "+" char	being added.

       This method caches the results of the test to use in future tests (at
       least until the next "connect()"	or "disconnect()" is executed).

   register()
       "Registering" on	the GSM	network	is what	happens	when you turn on your
       mobile phone or GSM equipment and the device tries to reach the GSM
       operator	network.  If your device requires a PIN	number,	it is used
       here (but remember to supply the	"pin" parameter	in new() object
       constructor for this to work.

       Registration can	take some seconds, don't worry for the wait.  After
       that, you are ready to send your	SMS messages or	do some	voice calls.
       Normally	you don't need to call register() explicitly because it	is
       done automatically for you when/if needed.

       If return value is true,	registration was successful, otherwise there
       is something wrong; probably you	supplied the wrong PIN code or network
       unreachable.

   send_sms()
       Obviously, this sends out SMS text messages. I should warn you that you
       cannot send (for	now) MMS, ringtone, smart, ota messages	of any kind
       with this method.

       Send out	an SMS message quickly:

	   my $sent = $gsm->send_sms(
	       content	 => 'Hello, world!',   # SMS text
	       recipient => '+99000123456',    # recipient phone number
	   );

	   if( $sent ) {
	       print "OK!";
	   } else {
	       print "Troubles...";
	   }

       The allowed parameters to send_sms() are:

       "class"
	   Class parameter can assume two values: "normal" and "flash".	Flash
	   (or class zero) messages are	particular because they	are
	   immediately displayed (without user confirm)	and never stored on
	   phone memory, while "normal"	is the default.

       "content"
	   This	is the text you	want to	send, consisting of max	160 chars if
	   you use PDU mode and	140 (?)	if in text mode	(more on this later).

       "mode"
	   Can assume two values (case insensitive): "pdu" and "text".	"PDU"
	   means Protocol Data Unit and	it is a	sort of	binary encoding	of
	   commands, to	save time/space, while "text" is the normal GSM
	   commands text mode.

	   Recent mobile phones	and GSM	equipment surely have support for
	   "PDU" mode.	Older OEM modules (like	Falcom Swing, for example)
	   don't have PDU mode,	but only text mode. It is just a matter	of
	   trying.

       "recipient"
	   Phone number	of message recipient

       "status_report"
	   If present with a true value, it enables sending of SMS messages
	   (only for PDU mode, text mode SMS won't be influenced by this
	   parameter) with the status report, also known as delivery report,
	   that	is a short message that	reports	the status of your sent
	   message.  Usually this is only available if your mobile company
	   supports this feature, and probably you will	be charged a small
	   amount for this service.

	   More	information on this would be welcome.

   service_center()
       If called without parameters, returns the actual	SMS Service Center
       phone number. This is the number	your phone automatically calls when
       receiving and sending SMS text messages,	and your network operator
       should tell you what this number	is.

       Example:

	   my $gsm = Device::Gsm->new( port => 'COM1' );
	   $gsm->connect() or die "Can't connect";
	   $srv_cnt = $gsm->service_center();
	   print "My service center number is: $srv_cnt\n";

       If you want to set or change this number	(if used improperly this can
       disable sending of SMS messages,	so be warned!),	you can	try something
       like:

	   my $ok = $gsm->service_center('+99001234567');
	   print "Service center changed!\n" if	$ok;

REQUIRES
       o   Device::Modem, which	in turn	requires

       o   Device::SerialPort (or Win32::SerialPort on Windows machines)

EXPORT
       None

TROUBLESHOOTING
       If you experience problems, please double check:

       Device permissions
	   Maybe you don't have	necessary permissions to access	your serial,
	   irda	or bluetooth port device. Try executing	your script as root,
	   or try, if you don't	mind, "chmod a+rw /dev/ttyS1" (or whatever
	   device you use instead of "/dev/ttyS1").

       Connection speed
	   Try switching "baudrate" parameter from 19200 (the default value)
	   to 9600 or viceversa. This one is the responsible of	80% of the
	   problems, because there is no baudrate auto-detection.

       Device autoscan
	   If all else fails, please use the autoscan utility in the "bin/"
	   folder of the "Device::Gsm" distribution. Try running this autoscan
	   utility and examine the log file produced in	the current directory.

	   If you lose any hope, send me this log file so I can	eventually
	   have	any clue about the problem / failure.

	   Also	this is	a profiling tool, to know which	commands are supported
	   by your device, so please send me profiles of your devices, so I
	   can add better support for all devices in the future!

TO-DO
       Spooler
	   Build a simple spooler program that sends all SMS stored in a
	   special queue (that could be	a simple filesystem folder).

       Validity	Period
	   Support "validity" period option on SMS sending. Tells how much
	   time	the SMS	Service	Center must hold the SMS for delivery when not
	   received.

AUTHOR
       Cosimo Streppone, cosimo@cpan.org

SEE ALSO
       Device::Modem, Device::SerialPort, Win32::SerialPort, perl(1)

perl v5.32.0			  2016-06-21			Device::Gsm(3)

NAME | SYNOPSIS | DESCRIPTION | WHY? | METHODS | REQUIRES | EXPORT | TROUBLESHOOTING | TO-DO | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Device::Gsm&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help