.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Device::Gsm 3pm" .TH Device::Gsm 3pm "2021-01-19" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Device::Gsm \- Perl extension to interface GSM phones / modems .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Device::Gsm; \& \& my $gsm = new Device::Gsm( port => \*(Aq/dev/ttyS1\*(Aq, pin => \*(Aqxxxx\*(Aq ); \& \& if( $gsm\->connect() ) { \& print "connected!\en"; \& } else { \& print "sorry, no connection with gsm phone on serial port!\en"; \& } \& \& # Register to GSM network (you must supply PIN number in above new() call) \& # See \*(Aqassume_registered\*(Aq in the new() method documentation \& $gsm\->register(); \& \& # Send quickly a short text message \& $gsm\->send_sms( \& recipient => \*(Aq+3934910203040\*(Aq, \& content => \*(AqHello world! from Device::Gsm\*(Aq \& ); \& \& # Get list of Device::Gsm::Sms message objects \& # see \`examples/read_messages.pl\*(Aq for all the details \& my @messages = $gsm\->messages(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`Device::Gsm\*(C'\fR class implements basic \s-1GSM\s0 functions, network registration and \s-1SMS\s0 sending. .PP This class supports also \f(CW\*(C`PDU\*(C'\fR mode to send \f(CW\*(C`SMS\*(C'\fR 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 \s-1GSM\s0 phones attached with a Siemens-compatible serial cable. After some years, I have developed and tested it with Linux Slackware 10.2 and a \fBCambridge Silicon Radio\fR (\s-1CSR\s0) \s-1USB\s0 bluetooth dongle, connecting to a Nokia 6600 phone. .PP 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. .PP Feel free to contact me if you have any trouble or you are interested in improving this software. .PP If you need a way to test your gsm module or phone, and you don't mind spending an \s-1SMS,\s0 use the \f(CW\*(C`examples/send_to_cosimo.pl\*(C'\fR script to notify me that \&\f(CW\*(C`Device::Gsm\*(C'\fR still works and works well with your device (thanks!). .PP Over the years, I have collected hundreds of messages from all over the world :\-) .SH "WHY?" .IX Header "WHY?" Why would you want to use this? .PP When I started writing this software, around year 2000, I needed a practical way to automatically send tens of \s-1SMS\s0 messages through my phone. .PP Fast forward to 2016, I barely use \s-1SMS\s0 messages anymore, and you can find plenty of \s-1TCP/IP\s0 based services to send \s-1SMS\s0 messages, maybe even for free. .PP The only motivation left would be to learn how \s-1AT\s0 commands work for \s-1GSM\s0 modules. I had lots of fun learning this, but it was so many years ago, and \&\s-1YMMV,\s0 as they say. .SH "METHODS" .IX Header "METHODS" The following documents all supported methods with simple examples of usage. .SS "\fBnew()\fP" .IX Subsection "new()" Inherited from Device::Modem. See Device::Modem documentation for more details. .PP The only mandatory argument is the \f(CW\*(C`port\*(C'\fR you want to use to connect to the \s-1GSM\s0 device: .PP .Vb 3 \& my $gsm = Device::Gsm\->new( \& port => \*(Aq/dev/ttyS0\*(Aq, \& ); .Ve .PP On some phones, you may experience problems in the \s-1GSM\s0 network registration step. For this reasons, you can pass a special \f(CW\*(C`assume_registered\*(C'\fR option to have Device::Gsm ignore the registration step and assume the device is already registered on the \s-1GSM\s0 network. Example: .PP .Vb 4 \& my $gsm = Device::Gsm\->new( \& port => \*(Aq/dev/ttyS0\*(Aq, \& assume_registered => 1, \& ); .Ve .PP If you want to send debugging information to your own log file instead of the default setting, you can: .PP .Vb 5 \& my $gsm = Device::Gsm\->new( \& port => \*(Aq/dev/ttyS1\*(Aq, \& log => \*(Aqfile,/tmp/myfile.log\*(Aq, \& loglevel => \*(Aqdebug\*(Aq, # default is \*(Aqwarning\*(Aq \& ); .Ve .SS "\fBconnect()\fP" .IX Subsection "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 \f(CW\*(C`Device::SerialPort\*(C'\fR (or \f(CW\*(C`Win32::SerialPort\*(C'\fR on Windows platform), as all parameters are passed to those classes' \fBconnect()\fR method. .PP The default value for \f(CW\*(C`baudrate\*(C'\fR parameter is \f(CW19200\fR. .PP Example: .PP .Vb 8 \& my $gsm = Device::Gsm\->new( port=>\*(Aq/dev/ttyS0\*(Aq, log=>\*(Aqsyslog\*(Aq ); \& # ... \& if( $gsm\->connect(baudrate => 19200) ) { \& print "Connected!"; \& } else { \& print "Could not connect, sorry!"; \& } \& # ... .Ve .SS "\fBdatetime()\fP" .IX Subsection "datetime()" Used to get or set your phone/gsm modem date and time. .PP If called without parameters, it gets the current phone/gsm date and time in \&\*(L"gsm\*(R" format, \*(L"\s-1YY/MM/DD,HH:MN:SS\*(R".\s0 For example \f(CW\*(C`03/12/15,22:48:59\*(C'\fR means December the 15th, at 10:48:59 \s-1PM.\s0 Example: .PP .Vb 1 \& $datestr = $gsm\->datetime(); .Ve .PP If called with parameters, sets the current phone/gsm date and time to that of supplied value. Example: .PP .Vb 1 \& $newdate = $gsm\->datetime( time() ); .Ve .PP where \f(CW\*(C`time()\*(C'\fR is the perl's builtin \f(CW\*(C`time()\*(C'\fR function (see \&\f(CW\*(C`perldoc \-f time\*(C'\fR for details). Another variant allows one to pass a \&\f(CW\*(C`localtime\*(C'\fR array to set the correspondent datetime. Example: .PP .Vb 1 \& $newdate = $gsm\->datetime( localtime() ); .Ve .PP (Note the list context). Again you can read the details for \f(CW\*(C`localtime\*(C'\fR function with \f(CW\*(C`perldoc \-f localtime\*(C'\fR. .PP If your device does not support this command, an \fBundefined\fR value will be returned in either case. .SS "\fBdelete_sms()\fP" .IX Subsection "delete_sms()" This method deletes a message from your \s-1SIM\s0 card, given the message index number. Example: .PP .Vb 1 \& $gsm\->delete_sms(3); .Ve .PP An optional second parameter specifies the \*(L"storage\*(R". It allows one to delete messages from gsm phone memory or sim card memory. Example: .PP .Vb 2 \& # Deletes first message from gsm phone memory \& $gsm\->delete_sms(1, \*(AqME\*(Aq); \& \& # Deletes 3rd message from sim card \& $gsm\->delete_sms(3, \*(AqSM\*(Aq); .Ve .PP By default, it uses the currently set storage, via the \f(CW\*(C`storage()\*(C'\fR method. .SS "\fBforward()\fP" .IX Subsection "forward()" Sets call forwarding. Accepts three arguments: reason, mode and number. Reason can be the string \f(CW\*(C`unconditional\*(C'\fR, \f(CW\*(C`busy\*(C'\fR, \f(CW\*(C`no reply\*(C'\fR and \&\f(CW\*(C`unreachable\*(C'\fR. Mode can be the string \f(CW\*(C`disable\*(C'\fR, \f(CW\*(C`enable\*(C'\fR, \f(CW\*(C`query\*(C'\fR, \&\f(CW\*(C`register\*(C'\fR, \f(CW\*(C`erase\*(C'\fR. .PP Example: .PP .Vb 2 \& # Set unconditional call forwarding to +47 123456789 \& $gsm\->forward(\*(Aqunconditional\*(Aq,\*(Aqregister\*(Aq,\*(Aq+47123456789\*(Aq); \& \& # Erase unconditional call forwarding \& $gsm\->forward(\*(Aqunconditional\*(Aq,\*(Aqerase\*(Aq); .Ve .SS "\fBhangup()\fP" .IX Subsection "hangup()" Hangs up the phone, terminating the active calls, if any. This method has been never tested on real \*(L"live\*(R" conditions, but it needs to be specialized for \s-1GSM\s0 phones, because it relies on \f(CW\*(C`+HUP\*(C'\fR \s-1GSM\s0 command. Example: .PP .Vb 1 \& $gsm\->hangup(); .Ve .SS "\fBimei()\fP" .IX Subsection "imei()" Returns the device own \s-1IMEI\s0 number (\fBInternational Mobile Station Equipment Identity\fR). .PP This identifier is numeric and is supposed to be unique among all \s-1GSM\s0 mobile devices and phones. Example: .PP .Vb 1 \& my $imei = $gsm\->imei(); .Ve .SS "\fBmanufacturer()\fP" .IX Subsection "manufacturer()" Returns the device manufacturer, usually only the first word (example: \f(CW\*(C`Nokia\*(C'\fR, \&\f(CW\*(C`Siemens\*(C'\fR, \f(CW\*(C`Falcom\*(C'\fR, ...). Example: .PP .Vb 6 \& my $man_name = $gsm\->manufacturer(); \& if( $man_name eq \*(AqNokia\*(Aq ) { \& print "We have a nokia phone..."; \& } else { \& print "We have a $man_name phone..."; \& } .Ve .SS "\fBmessages()\fP" .IX Subsection "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 \s-1SMS\s0 messages stored on your \s-1SIM\s0 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 \f(CW\*(C`Device::Gsm::Sms\*(C'\fR object. .PP The only parameter specifies the \f(CW\*(C`storage\*(C'\fR 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): .ie n .IP """ME""" 4 .el .IP "\f(CWME\fR" 4 .IX Item "ME" Means gsm phone \fB\s-1ME\s0\fRmory .ie n .IP """MT""" 4 .el .IP "\f(CWMT\fR" 4 .IX Item "MT" Means gsm phone \fB\s-1ME\s0\fRmory on Nokia phones? .ie n .IP """SM""" 4 .el .IP "\f(CWSM\fR" 4 .IX Item "SM" Means \fBS\fRim card \fBM\fRemory (default value) .PP Example: .PP .Vb 2 \& my $gsm = Device::Gsm\->new(); \& $gsm\->connect(port=>\*(Aq/dev/ttyS0\*(Aq) or die "Can\*(Aqt connect!"; \& \& for( $gsm\->messages(\*(AqSM\*(Aq) ) \& { \& print $_\->sender(), \*(Aq: \*(Aq, $_\->content(), "\en"; \& } .Ve .SS "\fBmode()\fP" .IX Subsection "mode()" Sets the device \s-1GSM\s0 command mode. Accepts one parameter to set the new mode that can be the string \f(CW\*(C`text\*(C'\fR or \f(CW\*(C`pdu\*(C'\fR. Example: .PP .Vb 2 \& # Set text mode \& $gsm\->mode(\*(Aqtext\*(Aq); \& \& # Set pdu mode \& $gsm\->mode(\*(Aqpdu\*(Aq); .Ve .SS "\fBmodel()\fP" .IX Subsection "model()" Returns phone/device model name or number. Example: .PP .Vb 1 \& my $model = $gsm\->model(); .Ve .PP For example, for Siemens C45, \f(CW$model\fR holds \f(CW\*(C`C45\*(C'\fR; for Nokia 6600, \f(CW$model\fR holds \f(CW6600\fR. .SS "\fBnetwork()\fP" .IX Subsection "network()" Returns the current registered or preferred \s-1GSM\s0 network operator. Example: .PP .Vb 2 \& my $net_name = $gsm\->network(); \& # Returns \*(AqWind Telecom Spa\*(Aq \& \& my($net_name, $net_code) = $gsm\->network(); \& # Returns (\*(AqWind Telecom Spa\*(Aq, \*(Aq222 88\*(Aq) .Ve .PP This obviously varies depending on country and network operator. For me now, it holds \*(L"Wind Telecomunicazioni SpA\*(R". It is not guaranteed that the mobile phone returns the decoded network name. It can also return a gsm network code, like \f(CW\*(C`222 88\*(C'\fR. In this case, an attempt to decode the network name is made. .PP Be sure to call the \f(CW\*(C`network()\*(C'\fR method when already registered to gsm network. See \f(CW\*(C`register()\*(C'\fR method. .SS "\fBsignal_quality()\fP" .IX Subsection "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 \f(CW\*(C`\-91\*(C'\fR. Values should range from \-113 to \-51 dBm, where \-113 is the minimum signal quality and \-51 is the theoretical maximum quality. .PP .Vb 1 \& my $level = $gsm\->signal_quality(); .Ve .PP If signal quality can't be read or your device does not support this command, an \fBundefined\fR value will be returned. .SS "\fBsoftware_version()\fP" .IX Subsection "software_version()" Returns the device firmware version, as stored by the manufacturer. Example: .PP .Vb 1 \& my $rev = $gsm\->software_revision(); .Ve .PP For example, for my Siemens C45, \f(CW$rev\fR holds \f(CW06\fR. .SS "\fBstorage()\fP" .IX Subsection "storage()" Allows getting/setting 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 \f(CW\*(C`+CPMS\*(C'\fR \s-1AT\s0 command won't be affected by this method. .PP .Vb 3 \& my @msg; \& my $storage = $gsm\->storage(); \& print "Current storage is $storage\en"; \& \& # Read all messages on sim card \& $gsm\->storage(\*(AqSM\*(Aq); \& @msg = $gsm\->messages(); \& \& # Read messages from gsm phone memory \& $gsm\->storage(\*(AqME\*(Aq); \& push @msg, $gsm\->messages(); .Ve .SS "\fBtest_command()\fP" .IX Subsection "test_command()" This method queries the device to know if a specific \s-1AT GSM\s0 command is supported. This is used only with \s-1GSM\s0 commands (those with \f(CW\*(C`AT+\*(C'\fR prefix). For example, if I want to know if my device supports the \f(CW\*(C`AT+GXXX\*(C'\fR command: .PP .Vb 1 \& my $gsm = Device::Gsm\->new( port => \*(Aq/dev/myport\*(Aq ); \& \& ... \& \& if( $gsm\->test_command(\*(AqGXXX\*(Aq) ) { \& # Ok, command is supported \& } else { \& # Nope, no GXXX command \& } .Ve .PP Note that if you omit the starting \f(CW\*(C`+\*(C'\fR character, it is automatically added. You can also test commands like \f(CW\*(C`^SNBR\*(C'\fR or the like, without \f(CW\*(C`+\*(C'\fR char being added. .PP This method caches the results of the test to use in future tests (at least until the next \f(CW\*(C`connect()\*(C'\fR or \f(CW\*(C`disconnect()\*(C'\fR is executed). .SS "\fBregister()\fP" .IX Subsection "register()" \&\*(L"Registering\*(R" on the \s-1GSM\s0 network is what happens when you turn on your mobile phone or \s-1GSM\s0 equipment and the device tries to reach the \s-1GSM\s0 operator network. If your device requires a \fB\s-1PIN\s0\fR number, it is used here (but remember to supply the \f(CW\*(C`pin\*(C'\fR parameter in \fBnew()\fR object constructor for this to work. .PP Registration can take some seconds, don't worry for the wait. After that, you are ready to send your \s-1SMS\s0 messages or do some voice calls. Normally you don't need to call \fBregister()\fR explicitly because it is done automatically for you when/if needed. .PP If return value is true, registration was successful, otherwise there is something wrong; probably you supplied the wrong \s-1PIN\s0 code or network unreachable. .SS "\fBsend_sms()\fP" .IX Subsection "send_sms()" Obviously, this sends out \s-1SMS\s0 text messages. I should warn you that \&\fByou cannot send\fR (for now) \s-1MMS,\s0 ringtone, smart, ota messages of any kind with this method. .PP Send out an \s-1SMS\s0 message quickly: .PP .Vb 4 \& my $sent = $gsm\->send_sms( \& content => \*(AqHello, world!\*(Aq, # SMS text \& recipient => \*(Aq+99000123456\*(Aq, # recipient phone number \& ); \& \& if( $sent ) { \& print "OK!"; \& } else { \& print "Troubles..."; \& } .Ve .PP The allowed parameters to \fBsend_sms()\fR are: .ie n .IP """class""" 4 .el .IP "\f(CWclass\fR" 4 .IX Item "class" Class parameter can assume two values: \f(CW\*(C`normal\*(C'\fR and \f(CW\*(C`flash\*(C'\fR. Flash (or class zero) messages are particular because they are immediately displayed (without user confirm) and never stored on phone memory, while \f(CW\*(C`normal\*(C'\fR is the default. .ie n .IP """content""" 4 .el .IP "\f(CWcontent\fR" 4 .IX Item "content" This is the text you want to send, consisting of max 160 chars if you use \fB\s-1PDU\s0\fR mode and 140 (?) if in \fBtext\fR mode (more on this later). .ie n .IP """mode""" 4 .el .IP "\f(CWmode\fR" 4 .IX Item "mode" Can assume two values (case insensitive): \f(CW\*(C`pdu\*(C'\fR and \f(CW\*(C`text\*(C'\fR. \&\f(CW\*(C`PDU\*(C'\fR means \fBProtocol Data Unit\fR and it is a sort of \fBbinary\fR encoding of commands, to save time/space, while \f(CW\*(C`text\*(C'\fR is the normal \s-1GSM\s0 commands text mode. .Sp Recent mobile phones and \s-1GSM\s0 equipment surely have support for \f(CW\*(C`PDU\*(C'\fR mode. Older \s-1OEM\s0 modules (like Falcom Swing, for example) don't have \s-1PDU\s0 mode, but only text mode. It is just a matter of trying. .ie n .IP """recipient""" 4 .el .IP "\f(CWrecipient\fR" 4 .IX Item "recipient" Phone number of message recipient .ie n .IP """status_report""" 4 .el .IP "\f(CWstatus_report\fR" 4 .IX Item "status_report" If present with a true value, it enables sending of \s-1SMS\s0 messages (only for \s-1PDU\s0 mode, text mode \s-1SMS\s0 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. .Sp More information on this would be welcome. .SS "\fBservice_center()\fP" .IX Subsection "service_center()" If called without parameters, returns the actual \s-1SMS\s0 Service Center phone number. This is the number your phone automatically calls when receiving and sending \s-1SMS\s0 text messages, and your network operator should tell you what this number is. .PP Example: .PP .Vb 4 \& my $gsm = Device::Gsm\->new( port => \*(AqCOM1\*(Aq ); \& $gsm\->connect() or die "Can\*(Aqt connect"; \& $srv_cnt = $gsm\->service_center(); \& print "My service center number is: $srv_cnt\en"; .Ve .PP If you want to set or change this number (if used improperly this can disable sending of \s-1SMS\s0 messages, so be warned!), you can try something like: .PP .Vb 2 \& my $ok = $gsm\->service_center(\*(Aq+99001234567\*(Aq); \& print "Service center changed!\en" if $ok; .Ve .SH "REQUIRES" .IX Header "REQUIRES" .IP "\(bu" 4 Device::Modem, which in turn requires .IP "\(bu" 4 Device::SerialPort (or Win32::SerialPort on Windows machines) .SH "EXPORT" .IX Header "EXPORT" None .SH "TROUBLESHOOTING" .IX Header "TROUBLESHOOTING" If you experience problems, please double check: .IP "Device permissions" 4 .IX Item "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, \f(CW\*(C`chmod a+rw /dev/ttyS1\*(C'\fR (or whatever device you use instead of \f(CW\*(C`/dev/ttyS1\*(C'\fR). .IP "Connection speed" 4 .IX Item "Connection speed" Try switching \f(CW\*(C`baudrate\*(C'\fR 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. .IP "Device autoscan" 4 .IX Item "Device autoscan" If all else fails, please use the \fBautoscan\fR utility in the \f(CW\*(C`bin/\*(C'\fR folder of the \f(CW\*(C`Device::Gsm\*(C'\fR distribution. Try running this autoscan utility and examine the log file produced in the current directory. .Sp If you lose any hope, send me this log file so I can eventually have any clue about the problem / failure. .Sp 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! .SH "TO-DO" .IX Header "TO-DO" .IP "Spooler" 4 .IX Item "Spooler" Build a simple spooler program that sends all \s-1SMS\s0 stored in a special queue (that could be a simple filesystem folder). .IP "Validity Period" 4 .IX Item "Validity Period" Support \f(CW\*(C`validity\*(C'\fR period option on \s-1SMS\s0 sending. Tells how much time the \s-1SMS\s0 Service Center must hold the \s-1SMS\s0 for delivery when not received. .SH "AUTHOR" .IX Header "AUTHOR" Cosimo Streppone, cosimo@cpan.org .SH "SEE ALSO" .IX Header "SEE ALSO" Device::Modem, Device::SerialPort, Win32::SerialPort, \fBperl\fR\|(1)