Device::Gsm(3pm)

📦

version 1.61 · 2 versions

1.61 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
1.61 · arch rolling

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Device::Gsm — the Perl manual page 💖

okay bestie, pull up a chair, we're reading the Device::Gsm(3pm) manual together and honestly? it's giving "vintage tech girlie with a serial cable" and I am obsessed.

✨ NAME ✨

Device::Gsm — Perl extension to interface GSM phones / modems 🦋

✨ SYNOPSIS ✨

okay so here's the vibe, in code, exactly as written:

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

like, we're literally talking to a phone through Perl. main character energy fr fr. 💅

✨ DESCRIPTION ✨

The Device::Gsm class implements basic GSM functions, network registration and SMS sending. no cap.

It also supports PDU mode for sending SMS messages, and it should be fairly usable. Back in the day (and I mean back in the day), this was developed and tested under Linux RedHat 7.1 with a 16550 serial port and Siemens C35i/C45 GSM phones hooked up with a Siemens-compatible serial cable. Then, some years later, it got developed and tested with Linux Slackware 10.2 and a Cambridge Silicon Radio (CSR) USB bluetooth dongle, connecting to a Nokia 6600 phone. 🌈

and then... the plot twist 😭 Currently the author doesn't use this software anymore. It should probably still work, but it's unlikely they'll ever be able to test it with a real gsm module again. rip the testing era, you were iconic.

If you have any trouble, or you're interested in improving this software, feel free to contact them. 🫶

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 them that Device::Gsm still works and works well with your device (thanks!). Over the years, they've collected hundreds of messages from all over the world :-) hundreds!! global girlies!! 🌍💖

💭 WHY? 💭

bestie, you might be asking: why would you want to use this?

When the author started writing this software, around year 2000, they needed a practical way to automatically send tens of SMS messages through their phone. tens!! of them!! automated!!

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

So the only motivation left would be to learn how AT commands work for GSM modules. They 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 reason, 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. lowkey a lifesaver. 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'
    );

note the # default is 'warning' — that's not me being cute, that's literally the default 💖

🌸 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 as Device::SerialPort (or Win32::SerialPort on Windows platform), since 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, it sets the current phone/gsm date and time to that of the 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 the 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 never been tested on real "live" conditions, but it needs to be specialized for GSM phones, because it relies on +HUP GSM command. Example:

    $gsm->hangup();

heads up bestie: never tested on real "live" conditions. just so you know. 🙈

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

okay so 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";
    }

note the ? after "Nokia phones" — that's not me being unsure, that's the manual being unsure, and I respect the honesty 💜

🌸 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 the author 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. 💅

important bestie: 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 the 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 the author's Siemens C45, $rev holds 06. ✨

🌸 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 +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
    }

and that's part one bestie!! more coming, don't go anywhere 💖✨

Okay so real quick, bestie — if you omit the starting + character, it is automatically added. 💖 You can also test commands like ^SNBR or the like, without + char being added. So flexible! ✨

This method caches the results of the test to use in future tests (at least until the next connect() or disconnect() is executed). So it remembers, okay? 🧠💅

`register()` — the network glow-up 🌐✨

"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;

⚠️ Warning: if used improperly this can disable sending of SMS messages, so be warned! (We already said it but dramatic emphasis.)

REQUIRES 📦

Device::Modem, which in turn requires
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

Device::Gsm(3pm)

💖 Device::Gsm — the Perl manual page 💖

✨ NAME ✨

✨ SYNOPSIS ✨

✨ DESCRIPTION ✨

💭 WHY? 💭

✨ METHODS ✨

🌸 new() 🌸

🌸 connect() 🌸

🌸 datetime() 🌸

🌸 delete_sms() 🌸

🌸 forward() 🌸

🌸 hangup() 🌸

🌸 imei() 🌸

🌸 manufacturer() 🌸

🌸 messages() 🌸

🌸 mode() 🌸

🌸 model() 🌸

🌸 network() 🌸

🌸 signal_quality() 🌸

🌸 software_version() 🌸

🌸 storage() 🌸

🌸 test_command() 🌸

register() — the network glow-up 🌐✨

send_sms() 📲💌

service_center() 📞

REQUIRES 📦

EXPORT 🚫

TROUBLESHOOTING 🛠️

Device permissions 🔐

Connection speed ⚡

Device autoscan 🔍

TO-DO 📝

Spooler 🗂️

Validity Period ⏳

AUTHOR 👑

SEE ALSO 👀

`register()` — the network glow-up 🌐✨

`send_sms()` 📲💌

`service_center()` 📞