view release on metacpan or  search on metacpan

SerialPort.pm  view on Meta::CPAN

  $PortObj->are_match("-re", "pattern", "text");
      # possible match strings: "pattern" is a regular expression,
      #                         "text" is a literal string

=head1 DESCRIPTION

This module provides an object-based user interface essentially
identical to the one provided by the Win32::SerialPort module.

=head2 Initialization

The primary constructor is B<new> with either a F<PortName>, or a
F<Configuretion File> specified.  With a F<PortName>, this
will open the port and create the object. The port is not yet ready
for read/write access. First, the desired I<parameter settings> must
be established. Since these are tuning constants for an underlying
hardware driver in the Operating System, they are all checked for
validity by the methods that set them. The B<write_settings> method
updates the port (and will return True under POSIX). Ports are opened
for binary transfers. A separate C<binmode> is not needed.

  $PortObj = new Device::SerialPort ($PortName, $quiet, $lockfile)
       || die "Can't open $PortName: $!\n";

The C<$quiet> parameter is ignored and is only there for compatibility
with Win32::SerialPort.  The C<$lockfile> parameter is optional.  It will
attempt to create a file (containing just the current process id) at the
location specified. This file will be automatically deleted when the
C<$PortObj> is no longer used (by DESTROY). You would usually request
C<$lockfile> with C<$quiet> true to disable messages while attempting
to obtain exclusive ownership of the port via the lock. Lockfiles are
experimental in Version 0.07. They are intended for use with other
applications. No attempt is made to resolve port aliases (/dev/modem ==
/dev/ttySx) or to deal with login processes such as getty and uugetty.

Using a F<Configuration File> with B<new> or by using second constructor,
B<start>, scripts can be simplified if they need a constant setup. It
executes all the steps from B<new> to B<write_settings> based on a previously
saved configuration. This constructor will return C<undef> on a bad
configuration file or failure of a validity check. The returned object is
ready for access. This is new and experimental for Version 0.055.

  $PortObj2 = start Device::SerialPort ($Configuration_File_Name)
       || die;

The third constructor, B<tie>, will combine the B<start> with Perl's
support for tied FileHandles (see I<perltie>). Device::SerialPort will
implement the complete set of methods: TIEHANDLE, PRINT, PRINTF,
WRITE, READ, GETC, READLINE, CLOSE, and DESTROY. Tied FileHandle
support is new with Version 0.04 and the READ and READLINE methods
were added in Version 0.06. In "scalar context", READLINE sets B<stty_icanon>
to do character processing and calls B<lookfor>. It restores B<stty_icanon>
after the read. In "list context", READLINE does Canonical (line) reads if
B<stty_icanon> is set or calls B<streamline> if it is not. (B<stty_icanon>
is not altered). The B<streamline> choice allows duplicating the operation
of Win32::SerialPort for cross-platform scripts. 

The implementation attempts to mimic STDIN/STDOUT behaviour as closely
as possible: calls block until done and data strings that exceed internal
buffers are divided transparently into multiple calls. In Version 0.06,
the output separators C<$,> and C<$\> are also applied to PRINT if set.
The B<output_record_separator> and B<output_field_separator> methods can set
I<Port-FileHandle-Specific> versions of C<$,> and C<$\> if desired. Since
PRINTF is treated internally as a single record PRINT, C<$\> will be applied.
Output separators are not applied to WRITE (called as
C<syswrite FH, $scalar, $length, [$offset]>).
The input_record_separator C<$/> is not explicitly supported - but an
identical function can be obtained with a suitable B<are_match> setting.

  $PortObj2 = tie (*FH, 'Device::SerialPort', $Configuration_File_Name)
       || die;

The tied FileHandle methods may be combined with the Device::SerialPort
methods for B<read, input>, and B<write> as well as other methods. The
typical restrictions against mixing B<print> with B<syswrite> do not
apply. Since both B<(tied) read> and B<sysread> call the same C<$ob-E<gt>READ>
method, and since a separate C<$ob-E<gt>read> method has existed for some
time in Device::SerialPort, you should always use B<sysread> with the
tied interface (when it is implemented).

=over 8

Certain parameters I<SHOULD> be set before executing B<write_settings>.
Others will attempt to deduce defaults from the hardware or from other
parameters. The I<Required> parameters are:

=item baudrate

Any legal value.

=item parity

One of the following: "none", "odd", "even".

By default, incoming parity is not checked.  This mimics the behavior
of most terminal programs (like "minicom").  If you need parity checking
enabled, please use the "stty_inpck" and "stty_istrip" functions.

=item databits

An integer from 5 to 8.

=item stopbits

Legal values are 1 and 2.

=item handshake

One of the following: "none", "rts", "xoff".

=back

Some individual parameters (eg. baudrate) can be changed after the
initialization is completed. These will be validated and will
update the I<serial driver> as required. The B<save> method will
write the current parameters to a file that B<start, tie,> and
B<restart> can use to reestablish a functional setup.

  $PortObj = new Win32::SerialPort ($PortName, $quiet)
       || die "Can't open $PortName: $^E\n";    # $quiet is optional