NAME

Device::Modem::SMSModem - Perl extension for Device::Modem module

WARNING

This software has a BETA status. It has been carefully tested with Huawei E173 and Huawei E398 (E3276), but since AT commands may be imlemented differently, 100% compliance with all dongles is not guaranteed. See SUPPORT section for details

SYNOPSIS

 use Device::Modem::SMSModem;

 my $modem = new Device::Modem::SMSModem(
     port     => '/dev/ttyUSB0',
     log      => 'file,smstest.log',
     loglevel => 'info');
  
 if ($modem->connect(baudrate => 38400)) {
     print "Modem connected\n";
 }
 else {
     die "Couldn't connect $!, stopped\n";
 }

 # get operator MCC+MNC
 my $op= $modem->get_operator_info();
 print "Operator name: ".$op->{"long_name"}." MCC ".$op->{"mcc"}." MNC:".$op->{"mnc"}."\n";
 # LAC+BTS ID
 my $loc= $modem->get_lac_dec();
 print "LAC: ".$loc->{"lac"}." CELL ID ".$loc->{"cell_id"}."\n";
 
 print "IMSI: ".$modem->get_imsi()."\n";

 # SMSC addr 
 print "SMSC address: ".$modem->get_smsc_address()."\n";

 print "Setting up SM storage...\n";
 $modem->init_sms_storage("SM");

 print "Cleaning up storage...\n";
 $modem->clean_sms_storage();

 print "Getting number of messages...\n";

 print "Number of messages in the storage: ".$modem->read_sms_count()."\n";

 print "Looking for new messages...\n";

 while(1)
 {
        
        my $n= $modem->new_sms_count();
        if($n)
        {
                print "Got $n new messages...\n";
                my $last= $modem->sms_count()-1; 
                my $sms= $modem->read_sms($last);
                print $sms->{"status"}." ".$sms->{"from"}." ".$sms->{"date_time"}." ".$sms->{"smsc"}." ".$sms->{"text"}."\n";
                $modem->delete_sms($last);
        }
        else
        {
                print "No new messages...\n";           
        }               
        sleep(10);
 }

DESCRIPTION

This is an extension of Device::Modem intended to be be used as high level API to handle SMS in USB dongles. It works (as base class Device::Modem) via serial port and implements basic SMS functionality handling through AT (Hayes) commands.

What the module can do

• Get network and registration details

• Get serving SMSC address

• Get IMSI

• Send SMS

• Receive SMS

• Handle SMS storage change

What it can be used for

• Simple SMS gateways to send/receive SMS

• SMS notification features

• Just a convenient way to get actual network environment

Limitations

• At the moment it works through SMS read (AT+CMGR) commands but not through SMS list (AT+CMGL), since I discovered that CMGL does not work on my dongle properly. This is not very ideal from SMS handling convenience point of view. As soon as I get device with AT+CMGL working it will be implemented as well

• Some SMS related commands (like setting SMSC address) has not been implemented. If these commands are really required please drop me a line to contacts below

METHODS

init_sms_storage

This method sets sms memory being used. If you rae going to use(receive) SMS the method MUST be called prior of usage Possible values:

• SM. It refers to the message storage area on the SIM card.

• ME. It refers to the message storage area on the GSM/GPRS modem or mobile phone. Usually its storage space is larger than that of the message storage area on the SIM card.

• MT. It refers to all message storage areas associated with the GSM/GPRS modem or mobile phone. For example, suppose a mobile phone can access two message storage areas: "SM" and "ME". The "MT" message storage area refers to the "SM" message storage area and the "ME" message storage area combined together.

• BM. It refers to the broadcast message storage area. It is used to store cell broadcast messages.

• SR. It refers to the status report message storage area. It is used to store status reports.

• TA. It refers to the terminal adaptor message storage area.

SM or ME are recommended. The same value is used for all type of messages

Example:

 $gsm->init_sms_storage("SM"); 

get_imsi

This method returns IMSI

Example:

my $imsi= $modem->get_imsi();

get_smsc_address

This method returns Serving SMSC address

Example:

my $imsi= $modem->get_smsc_address();

get_operator_info

This method returns Serving Operator and registration status. Works only for registered dongle, returns undef otherwise.

Example:

my $loc= $modem->get_operator_info(); print $loc->{"mcc"}; print $loc->{"mnc"}; print $loc->{"short_name"}; print $loc->{"long_name"}; print $loc->{"reg_status"}; # opStatus. works only for registered operators, always return 2

sms_send

This method sends SMS to the specified phone number. The SMS is sent in text mode (not PDU). Phone number is likely to be i the format your network is able to accept.

Example:

 $gsm->send_sms("+33123456", "Message to send as an SMS");

clean_sms_storage

This method removes all SMS in the storage

Example:

 $gsm->clean_sms_storage(); 

delete_sms

This method delete sms rom choosen storage. By default, removes a message from given index. Optionally it accepts a flag what says what to remove:

• 0. Meaning: Delete only the SMS message stored at the location index from the message storage area. This is the default value.

• 1. Meaning: Ignore the value of index and delete all SMS messages whose status is "received read" from the message storage area.

• 2. Meaning: Ignore the value of index and delete all SMS messages whose status is "received read" or "stored sent" from the message storage area.

• 3. Meaning: Ignore the value of index and delete all SMS messages whose status is "received read", "stored unsent" or "stored sent" from the message storage area.

• 4. Meaning: Ignore the value of index and delete all SMS messages from the message storage area.

Returns: 1 if success, 0 otherwise

Example:

 $gsm->delete_sms(0); #delete SMS at index 0
 $gsm->delete_sms(0, 1); # delete all READ SMS

read_sms_count

This method re-reads number of SMS available in pre-defined storage Returns: number of SMS, -1 in case of errors

Example:

 print $gsm->read_sms_count();

sms_count

This method returns number of SMS available in pre-defined storage read during last read_sms_count() call. Note- this method does not re-read actual sms count in the storage Returns: number of SMS, -1 in case of errors

Example:

 print $gsm->sms_count();

capacity

This method returns capacity of message storage being used Returns: capacity of the storagenumber of SMS, undef is storage has not been initialized

Example:

 print $gsm->capacity();

read_sms

This method reads sms for given index. Since CMGR is used to read SMS, the method has a side effect that after its call the SMS has a READ status. Returns: SMS structure, undef if unable to read or index is not valid

Example:

 my $last= $modem->sms_count()-1; 
 my $sms= $modem->read_sms($last);
 print $sms->{"status"}." ".$sms->{"from"}." ".$sms->{"date_time"}." ".$sms->{"smsc"}." ".$sms->{"text"}."\n";

list_sms

This method lists SMS for given status. Possible status values:

• "REC UNREAD" unread

• "REC READ" read

• "STO UNSENT" unsent

• "STO SENT" sent

• "ALL" all (default)

Returns: Array of SMS strucures (the same as for read_sms, except SMSC address), empty array if no SMS for given status found or unable to execute SMGL AT command

Example:

 my @list= $modem->list_sms();
 print "Found ".($#list+1). " messages:\n";
 foreach my $sms (@list)
 {
        print $sms->{"status"}." ".$sms->{"from"}." ".$sms->{"date_time"}." ".$sms->{"text"}."\n"\;
 }

new_sms_count

This method returns number of new SMS available in pre-defined storage. In fact it returns number of SMS appeared since last query Returns: number of SMS, -1 in case of errors

Example:

 print $gsm->new_sms_count();

get_lac_hex

This method returns vireless location info- ie LAC and CELL ID. The identifiers are returned as a reference to hash. The values are in hex format.

Example:

my $loc= $modem->get_lac_hex(); print $loc->{"lac"}; print $loc->{"cell_id"};

get_lac_dec

This method returns vireless location info- ie LAC and CELL ID. The identifiers are returned as a reference to hash. The values are in decimal format.

Example:

my $loc= $modem->get_lac_dec(); print $loc->{"lac"}; print $loc->{"cell_id"};

SUPPORT

Feel free to contact me at dmitriii@gmail.com for questions or suggestions. The code has been tested against Huawei E173 and Huawei E398 If you find that your modem is not compatible because of AT commands mismatch (it may be different in different dongles) please provide modem name and attach AT command output.

AUTHOR

Dmitry Cheban, dmitriii@gmail.com

COPYRIGHT

(c) 2015, Dmitry Cheban, dmitriii@gmail.com

This library is free software; you can only redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Device::Modem

cpanm Device::Modem::SMSModem

perl -MCPAN -e shell
install Device::Modem::SMSModem