Device::SerialPort
Hello Serial Port users:
If you are running Windows 95 or later, you want the Win32::SerialPort
module instead of this one. It has a compatible user interface.
Available from your favorite CPAN site. Since someone asked, there is
not currently an equivalent for MS-DOS (and none is anticipated).
This is a POSIX-based version of the Win32::Serialport module ported by
Joe Doss for the MisterHouse Home Automation Package from Version 0.08
of the Win32 module. He replaced calls to the Win32 API with similar
functions implemented using POSIX calls. While most of the testing has
occurred on linux, the package should work on other POSIX-compliant
Operating Systems.
Most of the functions from Win32::SerialPort are now available. Almost
all the demos and examples work with minimal modifications. Many of the
methods are new with this release or 0.06, so expect a few bugs and
consider everything experimental. But the intent is to "clone" the
corresponding features of the Win32::SerialPort module whenever
practical - see the documentation for that module as well as this one
for details.
Version 0.07 improved the lockfile support, added some application
variables that are saved in the configuration_file, and added the
ioctl-based methods status, modemlines, and write_done. These act
mostly like their Win32 cousins. Since they use ioctls, they are
only available on systems that "can_ioctl".
Version 0.09 adds further compatibility for other OSes, including AIX,
Solaris, and OpenBSD. Kees Cook is now maintaining this code for use
with the Sendpage tool (http://sendpage.org/).
Version 0.20 uses XS to figure out the serial/modem bits needed to do
all the state fiddling. Pay close attention to the "configure" output
warnings to find out about possible broken things on your system.
Version 1.0.0 changes the version number scheme to be like Perl itself.
COMPATIBILITY NOTES:
1. Earlier versions of this module were named SerialPort_Linux.pm or
just SerialPort.pm. The examples in alpha version 0.02 (limited
release only) work fine when the Namespace is updated.
2. Unlike Win32::SerialPort, this distribution uses Makefile.PL and the
"standard" install sequence for CPAN modules:
perl Makefile.PL
make
make test
make install
3. The GetTickCount method has been renamed to get_tick_count to conform
to normal naming style. A corresponding method has been added to the
Win32 version to facilitate portability.
4. The save, start, and restart methods are now supported. The format of
the configuration_file is not identical to the Win32 one.
5. Version 0.07 changes parts of the configuration_file. You will need
to save a new one - files from previous versions will not work.
6. Right now, AIX will also fail some of the tests, including setting
hardware flow control. I'm working on fixing this.
7. For Solaris, see the "SOLARIS TROUBLE" section below.
8. Please only use "read(255)" unless you've tested other reading methods.
There have been reports of dropped characters using other functions.
See the NOTES and KNOWN LIMITATIONS in the SerialPort documentation. The
".pod" is embedded in the ".pm". The comments on "-w" and "use strict"
are especially relevant when you start calling this module from your own
code. Special thanks to Joe Doss for the initial porting. And to Bruce
Winter for the "required *.ph" list. Also thanks to the others who have
contributed comments and suggestions. Thanks to Aaron Botsis for letting
me play with his OpenBSD box and watching DTR lights for me.
FILES:
README - this file
INSTALL - bare minimum instructions for installing
TODO - list of other stuff in need of coding
COPYING - software license
Changes - for history lovers
Makefile.PL - the "starting point" for traditional reasons
configure - used to find the correct headers for SerialPort.xs
config.h.in - used to build config.h, used by SerialPort.xs
MANIFEST - distribution file list
SerialPort.pm - the reason you're reading this
SerialPort.xs - the C code to get all the serial bits from .h files
modemtest - quick tool for checking on serial port
show-tiocm.c.test - simple C tool to report TIOCM* hacks
Device-SerialPort.spec - RPM .spec file for building RPMS
t - test directory
t/Altport.pm - stub for inheritance test
t/01timing.t - tests millisecond counter in "get_tick_count"
t/test1.t - tests basic port function
t/test2.t - tests restarting_a_configuration and timeouts
t/test3.t - Inheritance and export version of test1.t
t/test4.t - Inheritance version of test2.t and "restart"
eg/any_os.plx - cross-platform "conditional use" demo
eg/demo1.plx - talks to a "really dumb" terminal
eg/demo2.plx - "poor man's" readline and chatV
eg/demo3.plx - looks like a setup menu - but only looks :-(
eg/demo4.plx - simplest setup: "new", "required param"
eg/demo5.plx - "waitfor" and "nextline" using lookfor
eg/demo6.plx - basic tied FileHandle operations, record separators
eg/demo7.plx - a Perl/Tk based terminal, event loop and callbacks
eg/demo8.plx - command line terminal emulator with Term::Readkey
eq/options.plx - post-install test that prints available options
eg/example1.txt - examples from The Perl Journal #13
eg/example2.txt - (minimal mods for cross-platform use)
eg/example3.txt
eg/example4.txt
eg/example5.txt
eg/example6.txt
eg/example7.txt
eg/example8.txt
autotools/* - various tools used by the "configure" script
INSTALL and TEST:
You will need suitable permissions to open the port. If the port is also
used for logins, you will need to create a lockfile (/var/lock/LCK..ttyS0)
on my Redhat 5.2 system. Just touch it, the contents are not important.
They may be someday. But not yet. You might need to be "root" for that.
Run 'perl Makefile.PL' followed by 'make'. This will create install files
and directories. Run 'make test' with nothing connected to "/dev/ttyS1".
This will run the tests and create a configuration_file. You can specify
a different port to test via 'perl Makefile.PL TESTPORT=<DEVICE>'.
Makefile.PL creates "t/DefaultPort.pm". You can also specify an alternate
port with the Shell Variable "Makefile_Test_Port".
The Benchmark routines are used to generate reports. The test suite
covers many of the module methods and sets the port for 9600 baud,
1 stop, 8 data, no parity, no handshaking, and other defaults. At
various points in the testing, it expects unconnected CTS and DTR lines.
The module should restore any port settings on exit. But this has not
been exhaustively tested yet.
Tests may also be run individually by typing:
'perl test?.t Page_Delay [/dev/ttySx]'
With no delay, the tests execute too rapidly to follow from a command
line. Delay may be set from 0 to 5 seconds.
All tests are expected to pass - I would be very interested in hearing
about failures ("not ok"). These tests should be run from a command
prompt. For details run "make test TEST_VERBOSE=1".
SOLARIS TROUBLE:
The big problem is with Solaris' handling of DTR.
Depending on hardware, patchlevel, or something very mystical, if
you have an "se" or "zs" serial port (run "modinfo | grep serial"
to find out), you may need to correct this DTR bug by adding a
line to your /etc/system file. See below...
From the following URL:
http://www.stokely.com/unix.serial.port.resources/tutorials.html
DTR Delay Problems: By default, Suns have a three second
delay in toggling dtr. If your Sun has a zs serial port you
can set the variable default_dtrlow to control the number of
seconds of the delay. If the variable is set to zero, dtr
can be toggled many times a second. For example, in
/etc/system add the line "set zs:default_dtrlow = 1" to have
a 1 second delay.
If your workstation has an se serial port, the /etc/system
line should be "set se:se_default_dtrlow = 1". However, in
initial versions of the se driver, the delay was the value
of (se_default_dtrlow + 1) seconds. If you have this version
of the se driver, don't set the value to -1 in /etc/system or
the port will hang on open. If you need to toggle dtr quickly,
you can still set the value to -1 after the terminal is
opened by using adb to set the variable manually.
All this is Sun bugid 4230310, fixed by patch 105924-09 or
higher. The patch makes se_default_dtrlow behave like
default_dtrlow (i.e. setting se_default_dtrlow to 0 will allow
rapid toggling of dtr instead of once per second).
So, since I have zs serial ports on my Sun, I added the line:
set zs:default_dtrlow=0
so I could toggle the DTR rapidly.
There are also problems with "tcdrain" never returning if there
is no device attached to the serial port. This has been worked
around in the tests.
DEMO PROGRAMS:
Connect a dumb terminal (or a PC that acts like one) to /dev/ttyS0 and
setup the equivalent configuration. Starting demo1.plx should print a
three line message on both the terminal and the command line. The
terminal keyboard (only) now accepts characters which it prints to both
screens until a CONTROL-Z is typed. Also included is demo2.plx - a truly
minimal chat program. Bi-directional communication without an event loop,
sockets, pipes (or much utility ;-) This one uses CAPITAL-Q from the
active keyboard to quit since <STDIN> doesn't like CONTROL-Z.
AltPort.pm and test3.t implement the "basic Inheritance test" discussed
in perltoot and other documentation. It also imports the :PARAM constants.
It's otherwise only slightly modified from test1.t (you'll get a different
"alias" in test3.t).
Run options.plx to see the available choices for various parameters
along with the current values. If you have trouble, I will probably
ask you to save the output of options.plx in a file and send it to me.
You can specify a port name for options.plx on the command line
(e.g. 'perl options.plx COM2').
You can read (many of the important) settings with demo3.plx. If you
give it a (valid) configuration file on the command line, it will open
the port with those parameters - so you can test simple changes: see
the parity example at the end of demo3.plx.
Demo4.plx is a "minimum" script showing just the basics needed to get
started.
Demo5.plx demonstrates various uses of the lookfor routine including
setups for "waitfor" and a primitive "readline". Try them out. The
default "stty" settings work with a VT-100 style terminal. You may
have to set the options by hand. Use any editor. Let me know if the
descriptions in the documentation are useable. And if any more options
are necessary.
Demo6.plx demonstrates tied FileHandles. Perl 5.005 is recommended.
It "requires" 5.004. It implements timeouts on all user inputs - so
you can run it "hands-off" to see what happens.
Demo7.plx uses Tk to create a terminal emulator. Its included to show
polling and callbacks using an event loop.
Demo8.plx is a simple command-line terminal emulator contributed by
Andrej Mikus.
The Perl Journal #13 included an article on Controlling a Modem with
Win32::SerialPort. Slightly revised versions of all the Examples
from the article are included in the "eg" subdirectory. The revisions
cover cross-platform use and workarounds for small timing differences.
Please tell me what does and what doesn't work. The module has proven
to be pretty robust. But I can't test all possible configurations.
Don't trust it for anything important without complete testing.
And watch for updates at:
%%%% http://sendpage.org/device-serialport/
or CPAN under authors/id/C/CO/COOK or Device::SerialPort
Thanks,
-Kees <kees@outflux.net>
Copyright (C) 1999, Bill Birthisel. All rights reserved.
Copyright (C) 2001-2005 Kees Cook. All rights reserved.
This module is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
