NAME¶
Device::Modem - Perl extension to talk to modem devices connected via serial
port
WARNING¶
This is
BETA software, so use it at your own risk, and without
ANY
warranty! Have fun.
SYNOPSIS¶
use Device::Modem;
my $modem = new Device::Modem( port => '/dev/ttyS1' );
if( $modem->connect( baudrate => 9600 ) ) {
print "connected!\n";
} else {
print "sorry, no connection with serial port!\n";
}
$modem->attention(); # send `attention' sequence (+++)
($ok, $answer) = $modem->dial('02270469012'); # dial phone number
$ok = $modem->dial(3); # 1-digit parameter = dial number stored in memory 3
$modem->echo(1); # enable local echo (0 to disable)
$modem->offhook(); # Take off hook (ready to dial)
$modem->hangup(); # returns modem answer
$modem->is_active(); # Tests whether modem device is active or not
# So far it works for modem OFF/ modem ON condition
$modem->reset(); # hangup + attention + restore setting 0 (Z0)
$modem->restore_factory_settings(); # Handle with care!
$modem->restore_factory_settings(1); # Same with preset profile 1 (can be 0 or 1)
$modem->send_init_string(); # Send initialization string
# Now this is fixed to 'AT H0 Z S7=45 S0=0 Q0 V1 E0 &C0 X4'
# Get/Set value of S1 register
my $S1 = $modem->S_register(1);
my $S1 = $modem->S_register(1, 55); # Don't do that if you definitely don't know!
# Get status of managed signals (CTS, DSR, RLSD, RING)
my %signal = $modem->status();
if( $signal{DSR} ) { print "Data Set Ready signal active!\n"; }
# Stores this number in modem memory number 3
$modem->store_number(3, '01005552817');
$modem->repeat(); # Repeat last command
$modem->verbose(1); # Normal text responses (0=numeric codes)
# Some raw AT commands
$modem->atsend( 'ATH0' );
print $modem->answer();
$modem->atsend( 'ATDT01234567' . Device::Modem::CR );
print $modem->answer();
DESCRIPTION¶
"Device::Modem" class implements basic
AT (Hayes) compliant
device abstraction. It can be inherited by sub classes (as
"Device::Gsm"), which are based on serial connections.
Things "Device::Modem" can do
- •
- connect to a modem on your serial port
- •
- test if the modem is alive and working
- •
- dial a number and connect to a remote modem
- •
- work with registers and settings of the modem
- •
- issue standard or arbitrary "AT" commands,
getting results from modem
Things "Device::Modem" can't do yet
- •
- Transfer a file to a remote modem
- •
- Control a terminal-like (or a PPP) connection. This should
really not be very hard to do anyway.
- •
- Many others...
Things it will never be able to do
- •
- Coffee :-)
Examples
In the `examples' directory, there are some scripts that should work without big
problems, that you can take as (yea) examples:
- `examples/active.pl'
- Tests if modem is alive
- `examples/caller-id.pl'
- Waits for an incoming call and displays date, time and
phone number of the caller. Normally this is available everywhere, but you
should check your local phone line and settings.
- `examples/dial.pl'
- Dials a phone number and display result of call
- `examples/shell.pl'
- (Very) poor man's minicom/hyperterminal utility
- `examples/xmodem.pl'
- First attempt at a test script to receive a file via xmodem
protocol. Please be warned that this thing does not have a chance to work.
It's only a (very low priority) work in progress...
If you want to help out, be welcome!
METHODS¶
answer()
One of the most used methods, waits for an answer from the device. It waits
until $timeout (seconds) is reached (but don't rely on this time to be very
correct) or until an expected string is encountered. Example:
$answer = $modem->answer( [$expect [, $timeout]] )
Returns $answer that is the string received from modem stripped of all
Carriage Return and
Line Feed chars
only at the beginning
and at the end of the string. No in-between
CR+LF are stripped.
Note that if you need the raw answer from the modem, you can use the
_answer() (note that underscore char before answer) method, which does
not strip anything from the response, so you get the real modem answer string.
Parameters:
- •
- $expect - Can be a regexp compiled with "qr" or a
simple substring. Input coming from the modem is matched against this
parameter. If input matches, result is returned.
- •
- $timeout - Expressed in seconds. After that time, answer
returns result also if nothing has been received. Example: 10. Default:
0.2
atsend()
Sends a raw "AT" command to the device connected. Note that this
method is most used internally, but can be also used to send your own custom
commands. Example:
$ok = $modem->atsend( $msg )
The only parameter is $msg, that is the raw AT command to be sent to modem
expressed as string. You must include the "AT" prefix and final
Carriage Return and/or
Line Feed manually. There is the special
constant "CR" that can be used to include such a char sequence into
the at command.
Returns $ok flag that is true if all characters are sent successfully, false
otherwise.
Example:
# Enable verbose messages
$modem->atsend( 'AT V1' . Device::Modem::CR );
# The same as:
$modem->verbose(1);
attention()
This command sends an
attention sequence to modem. This allows modem to
pass in
command state and accept
AT commands. Example:
$ok = $modem->attention()
connect()
Connects "Device::Modem" object to the specified serial port. There
are options (the same options that "Device::SerialPort" has) to
control the parameters associated to serial link. Example:
$ok = $modem->connect( [%options] )
List of allowed options follows:
- "baudrate"
- Controls the speed of serial communications. The default is
19200 baud, that should be supported by all modern modems. However,
here you can supply a custom value. Common speed values: 300, 1200, 2400,
4800, 9600, 19200, 38400, 57600, 115200. This parameter is handled
directly by "Device::SerialPort" object.
- "databits"
- This tells how many bits your data word is composed of.
Default (and most common setting) is 8. This parameter is handled directly
by "Device::SerialPort" object.
- "init_string"
- Custom initialization string can be supplied instead of the
built-in one, that is the following: "H0 Z S7=45 S0=0 Q0 V1 E0
&C0 X4", that is taken shamelessly from "minicom"
utility, I think.
- "parity"
- Controls how parity bit is generated and checked. Can be
even, odd or none. Default is none. This
parameter is handled directly by "Device::SerialPort"
object.
- "stopbits"
- Tells how many bits are used to identify the end of a data
word. Default (and most common usage) is 1. This parameter is handled
directly by "Device::SerialPort" object.
dial()
Takes the modem off hook, dials the specified number and returns modem answer.
Usage:
# Simple usage (timeout is optional)
$ok = $modem->dial( $number [,$timeout] )
# List context: allows to get at exact modem answer
# like `CONNECT 19200/...', `BUSY', `NO CARRIER', ...
($ok, $answer) = $modem->dial( $number [,$timeout] )
If called in
scalar context, returns only success of connection. If modem
answer contains "CONNECT" string, "dial()" returns
successful state, else false value is returned.
If called in
list context, returns the same $ok flag, but also the exact
modem answer to the dial operation in the $answer scalar. $answer typically
can contain strings like "CONNECT 19200" or "NO CARRIER",
"BUSY", ... all standard modem answers to a dial command.
Parameters are:
- •
- $number - this is the phone number to dial. If $number is
only 1 digit, it is interpreted as: dial number in my address book
position $number. So if your code is:
$modem->dial( 2, 10 );
This means: dial number in the modem internal address book (see
"store_number" for a way to read/write address book) in position
number 2 and wait for a timeout of 10 seconds.
- •
- $timeout - timeout expressed in seconds to wait for the
remote device to answer. Please do not expect an exact wait for the
number of seconds you specified. I'm still studying how to do that
exactly.
disconnect()
Disconnects "Device::Modem" object from serial port. This method calls
underlying "disconnect()" of "Device::SerialPort" object.
Example:
$modem->disconnect();
echo()
Enables or disables local echo of commands. This is managed automatically by
"Device::Modem" object. Normally you should not need to worry about
this. Usage:
$ok = $modem->echo( $enable )
hangup()
Does what it is supposed to do. Hang up the phone thus terminating any active
call. Usage:
$ok = $modem->hangup();
is_active()
Can be used to check if there is a modem attached to your computer. If modem is
alive and responding (on serial link, not to a remote call),
"is_active()" returns true (1), otherwise returns false (0).
Test of modem activity is done through DSR (Data Set Ready) signal. If this
signal is in off state, modem is probably turned off, or not working. From my
tests I've found that DSR stays in "on" state after more or less one
second I turn off my modem, so know you know that.
Example:
if( $modem->is_active() ) {
# Ok!
} else {
# Modem turned off?
}
log()
Simple accessor to log object instanced at object creation time. Used
internally. If you want to know the gory details, see
"Device::Modem::Log::*" objects. You can also see the
examples for how to log something without knowing all the gory details.
Hint: $modem->log->write('warning', 'ok, my log message here');
new()
"Device::Modem" constructor. This takes several options. A basic
example:
my $modem = Device::Modem->new( port => '/dev/ttyS0' );
if under Linux or some kind of unix machine, or
my $modem = Device::Modem->new( port => 'COM1' );
if you are using a Win32 machine.
This builds the "Device::Modem" object with all the default
parameters. This should be fairly usable if you want to connect to a real
modem. Note that I'm testing it with a
3Com US Robotics 56K Message
modem at
19200 baud and works ok.
List of allowed options:
- •
- "port" - serial port to connect to. On Unix, can
be also a convenient link as /dev/modem (the default value). For
Win32, "COM1,2,3,4" can be used.
- •
- "log" - this specifies the method and eventually
the filename for logging. Logging process with "Device::Modem"
is controlled by log plugins, stored under Device/Modem/Log/
folder. At present, there are two main plugins: "Syslog" and
"File". "Syslog" does not work with Win32 machines.
When using "File" plug-in, all log information will be written
to a default filename if you don't specify one yourself. The default is
%WINBOOTDIR%\temp\modem.log on Win32 and /var/log/modem.log
on Unix.
Also there is the possibility to pass a custom log object, if this
object provides the following "write()" call:
$log_object->write( $loglevel, $logmessage )
You can simply pass this object (already instanced) as the "log"
property.
Examples:
# For Win32, default is to log in "%WINBOOTDIR%/temp/modem.log" file
my $modem = Device::Modem->new( port => 'COM1' );
# Unix, custom logfile
my $modem = Device::Modem->new( port => '/dev/ttyS0', log => 'file,/home/neo/matrix.log' )
# With custom log object
my $modem = Device::modem->new( port => '/dev/ttyS0', log => My::LogObj->new() );
- •
- "loglevel" - default logging level. One of (order
of decrescent verbosity): "debug", "verbose",
"notice", "info", "warning",
"err", "crit", "alert", "emerg".
offhook()
Takes the modem "off hook", ready to dial. Normally you don't need to
use this. Also "dial()" goes automatically off hook before dialing.
parse_answer()
This method works like "answer()", it accepts the same parameters, but
it does not return the raw modem answer. Instead, it returns the answer string
stripped of all
CR/
LF characters at the beginning
and at
the end.
"parse_answer()" is meant as an easy way of extracting result code
("OK", "ERROR", ...) and information strings that can be
sent by modem in response to specific commands. Example:
> AT xSHOW_MODELx<CR>
US Robotics 56K Message
OK
>
In this example, "OK" is the result and "US Robotics 56K
Message" is the informational message.
In fact, another difference with "answer()" is in the return value(s).
Here are some examples:
$modem->atsend( '?my_at_command?' );
$answer = $modem->parse_answer();
where $answer is the complete response string, or:
($result, @lines) = $modem->parse_answer();
where $result is the "OK" or "ERROR" final message and
@lines is the array of information messages (one or more lines). For the
model example, $result would hold ""OK"" and @lines
would consist of only 1 line with the string ""US Robotics 56K
Message"".
port()
Used internally. Accesses the "Device::SerialPort" underlying object.
If you need to experiment or do low-level serial calls, you may want to access
this. Please report any usage of this kind, because probably (?) it is
possible to include it in a higher level method.
repeat()
Repeats the last "AT" command issued. Usage:
$ok = $modem->repeat()
reset()
Tries in any possible way to reset the modem to the starting state, hanging up
all active calls, resending the initialization string and preparing to receive
"AT" commands.
restore_factory_settings()
Restores the modem default factory settings. There are normally two main
"profiles", two different memories for all modem settings, so you
can load profile 0 and profile 1, that can be different depending on your
modem manufacturer.
Usage:
$ok = $modem->restore_factory_settings( [$profile] )
If no $profile is supplied, 0 is assumed as default value.
Check on your modem hardware manual for the meaning of these
profiles.
S_register()
Gets or sets an
S register value. These are some internal modem registers
that hold important information that controls all modem behaviour. If you
don't know what you are doing, don't use this method. Usage:
$value = $modem->S_register( $reg_number [, $new_value] );
$reg_number ranges from 0 to 99 (sure?). If no $new_value is supplied, return
value is the current register value. If a $new_value is supplied (you want to
set the register value), return value is the new value or "undef" if
there was an error setting the new value.
<!-- Qui è spiegata da cani -->
Examples:
# Get value of S7 register
$modem->S_register(7);
# Set value of S0 register to 0
$modem->S_register(0, 0);
send_init_string()
Sends the initialization string to the connected modem. Usage:
$ok = $modem->send_init_string( [$init_string] );
If you specified an "init_string" as an option to "new()"
object constructor, that is taken by default to initialize the modem. Else you
can specify $init_string parameter to use your own custom intialization
string. Be careful!
status()
Returns status of main modem signals as managed by
"Device::SerialPort" (or "Win32::SerialPort") objects. The
signals reported are:
- CTS
- Clear to send
- DSR
- Data set ready
- RING
- Active if modem is ringing
- RLSD
- ??? Released line ???
Return value of "status()" call is a hash, where each key is a signal
name and each value is > 0 if signal is active, 0 otherwise. Usage:
...
my %sig = $modem->status();
for ('CTS','DSR','RING','RLSD') {
print "Signal $_ is ", ($sig{$_} > 0 ? 'on' : 'off'), "\n";
}
store_number()
Store telephone number in modem internal address book, to be dialed later (see
"dial()" method). Usage:
$ok = $modem->store_number( $position, $number )
where $position is the address book memory slot to store phone number (usually
from 0 to 9), and $number is the number to be stored in the slot. Return value
is true if operation was successful, false otherwise.
verbose()
Enables or disables verbose messages. This is managed automatically by
"Device::Modem" object. Normally you should not need to worry about
this. Usage:
$ok = $modem->verbose( $enable )
wait()
Waits (yea) for a given amount of time (in milliseconds). Usage:
$modem->wait( [$msecs] )
Wait is implemented via "select" system call. Don't know if this is
really a problem on some platforms.
REQUIRES¶
- Device::SerialPort (Win32::SerialPort for Win32
machines)
EXPORT¶
None
TO-DO¶
- AutoScan
- An AT command script with all interesting commands is run
when `autoscan' is invoked, creating a `profile' of the current device,
with list of supported commands, and database of brand/model-specific
commands
- Serial speed autodetect
- Now if you connect to a different baud rate than that of
your modem, probably you will get no response at all. It would be nice if
"Device::Modem" could auto-detect the speed to correctly connect
at your modem.
- File transfers
- It would be nice to implement "[xyz]modem" like
transfers between two "Device::Modem" objects connected with two
modems.
FAQ¶
There is a minimal FAQ document for this module online at
<
http://www.streppone.it/cosimo/work/perl/CPAN/Device-Modem/FAQ.html>
SUPPORT¶
Please feel free to contact me at my e-mail address cosimo@cpan.org for any
information, to resolve problems you can encounter with this module or for any
kind of commercial support you may need.
AUTHOR¶
Cosimo Streppone, cosimo@cpan.org
COPYRIGHT¶
(C) 2002-2006 Cosimo Streppone, cosimo@cpan.org
This library is free software; you can only redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO¶
Device::SerialPort, Win32::SerialPort, Device::Gsm, perl