new()

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()

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()

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()

    $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()

Example:

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

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

hangup()

    $gsm->hangup();

imei()

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

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

manufacturer()

    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()

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()

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

model()

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

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

network()

    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()

    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()

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

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

storage()

    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()

    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()

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()

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()

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;