| Device::Modem - Perl extension to talk to modem devices connected via serial port |
Device::Modem can doDevice::Modem can't do yetanswer()atsend()attention()connect()dial()disconnect()echo()hangup()is_active()log()new()offhook()parse_answer()port()repeat()reset()restore_factory_settings()S_register()send_init_string()status()store_number()verbose()wait()write_drain()
Device::Modem - Perl extension to talk to modem devices connected via serial port
This is BETA software, so use it at your own risk, and without ANY warranty! Have fun.
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();
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.
Device::Modem can doAT commands, getting results from modem
Device::Modem can't do yet
In the `examples' directory, there are some scripts that should work without big problems, that you can take as (yea) examples:
If you want to help out, be welcome!
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 milliseconds. After that time, answer returns result also if nothing
has been received. Example: 10000. Default: $Device::Modem::TIMEOUT, currently 500 ms.
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:
baudrateDevice::SerialPort object.
databits8.
This parameter is handled directly by Device::SerialPort object.
handshakenone, but can be either rts (hardware flow control)
or xoff (software flow control). These flow control modes may or may not
work depending on your modem device or software.
init_stringH0 Z S7=45 S0=0 Q0 V1 E0 &C0 X4, that is taken shamelessly from
minicom utility, I think.
parityDevice::SerialPort object.
stopbits1.
This parameter is handled directly by Device::SerialPort object.
dial()Dials a telephone number. Can perform both voice and data calls.
Usage:
$ok = $modem->dial($number);
$ok = $modem->dial($number, $timeout);
$ok = $modem->dial($number, $timeout, $mode);
Takes the modem off hook, dials the specified number and returns modem answer.
Regarding voice calls, you will not be able to send your voice through.
You probably have to connect an analog microphone, and just speak.
Or use a GSM phone. For voice calls, a simple ; is appended to the
number to be dialed.
If the number to dial is 1 digit only, extracts the number from the address book, provided your device has one. See store_number().
Examples:
# Simple usage. Timeout and mode are optional.
$ok = $mode->dial('123456789');
# List context: allows to get at exact modem answer
# like `CONNECT 19200/...', `BUSY', `NO CARRIER', ...
# Also, 30 seconds timeout
($ok, $answer) = $modem->dial('123456789', 30);
If called in scalar context, returns only success of connection.
If modem answer contains the CONNECT string, dial() returns
successful state, otherwise a 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 19200NO CARRIERBUSYand so on ... all standard modem answers to a dial command.
Parameters are:
$number$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.
$timeoutTimeout 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.
$modeDATA, as string.
Allows to specify the type of call. Can be either:
DATA (default)VOICE
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.
As of 1.52, port() will automatically try to reconnect if it detects
a bogus underlying port object. It will reconnect with the same options used
when connect()ing the first time.
If no connection has taken place yet, then no automatic reconnection will be attempted.
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:
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.
write_drain()Only a simple wrapper around Device::SerialPort::write_drain method.
Disabled for Win32 platform, that doesn't have that.
None
Device::Modem
could auto-detect the speed to correctly connect at your modem.
[xyz]modem like transfers between
two Device::Modem objects connected with two modems.
There is a minimal FAQ document for this module online at http://www.streppone.it/cosimo/work/perl/CPAN/Device-Modem/FAQ.html
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.
Cosimo Streppone, cosimo@cpan.org
(C) 2002-2014 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.
Device::SerialPort, Win32::SerialPort, Device::Gsm, perl
| Device::Modem - Perl extension to talk to modem devices connected via serial port |