| 1 |
Device::SerialPort |
| 2 |
|
| 3 |
Hello Serial Port users: |
| 4 |
|
| 5 |
If you are running Windows 95 or later, you want the Win32::SerialPort |
| 6 |
module instead of this one. It has a compatible user interface. |
| 7 |
Available from your favorite CPAN site. Since someone asked, there is |
| 8 |
not currently an equivalent for MS-DOS (and none is anticipated). |
| 9 |
|
| 10 |
This is a POSIX-based version of the Win32::Serialport module ported by |
| 11 |
Joe Doss for the MisterHouse Home Automation Package from Version 0.08 |
| 12 |
of the Win32 module. He replaced calls to the Win32 API with similar |
| 13 |
functions implemented using POSIX calls. While most of the testing has |
| 14 |
occurred on linux, the package should work on other POSIX-compliant |
| 15 |
Operating Systems. |
| 16 |
|
| 17 |
Most of the functions from Win32::SerialPort are now available. Almost |
| 18 |
all the demos and examples work with minimal modifications. Many of the |
| 19 |
methods are new with this release or 0.06, so expect a few bugs and |
| 20 |
consider everything experimental. But the intent is to "clone" the |
| 21 |
corresponding features of the Win32::SerialPort module whenever |
| 22 |
practical - see the documentation for that module as well as this one |
| 23 |
for details. |
| 24 |
|
| 25 |
Version 0.07 improved the lockfile support, added some application |
| 26 |
variables that are saved in the configuration_file, and added the |
| 27 |
ioctl-based methods status, modemlines, and write_done. These act |
| 28 |
mostly like their Win32 cousins. Since they use ioctls, they are |
| 29 |
only available on systems that "can_ioctl". |
| 30 |
|
| 31 |
Version 0.09 adds further compatibility for other OSes, including AIX, |
| 32 |
Solaris, and OpenBSD. Kees Cook is now maintaining this code for use |
| 33 |
with the Sendpage tool (http://sendpage.org/). |
| 34 |
|
| 35 |
Version 0.20 uses XS to figure out the serial/modem bits needed to do |
| 36 |
all the state fiddling. Pay close attention to the "configure" output |
| 37 |
warnings to find out about possible broken things on your system. |
| 38 |
|
| 39 |
Version 1.0.0 changes the version number scheme to be like Perl itself. |
| 40 |
|
| 41 |
COMPATIBILITY NOTES: |
| 42 |
|
| 43 |
1. Earlier versions of this module were named SerialPort_Linux.pm or |
| 44 |
just SerialPort.pm. The examples in alpha version 0.02 (limited |
| 45 |
release only) work fine when the Namespace is updated. |
| 46 |
|
| 47 |
2. Unlike Win32::SerialPort, this distribution uses Makefile.PL and the |
| 48 |
"standard" install sequence for CPAN modules: |
| 49 |
perl Makefile.PL |
| 50 |
make |
| 51 |
make test |
| 52 |
make install |
| 53 |
|
| 54 |
3. The GetTickCount method has been renamed to get_tick_count to conform |
| 55 |
to normal naming style. A corresponding method has been added to the |
| 56 |
Win32 version to facilitate portability. |
| 57 |
|
| 58 |
4. The save, start, and restart methods are now supported. The format of |
| 59 |
the configuration_file is not identical to the Win32 one. |
| 60 |
|
| 61 |
5. Version 0.07 changes parts of the configuration_file. You will need |
| 62 |
to save a new one - files from previous versions will not work. |
| 63 |
|
| 64 |
6. Right now, AIX will also fail some of the tests, including setting |
| 65 |
hardware flow control. I'm working on fixing this. |
| 66 |
|
| 67 |
7. For Solaris, see the "SOLARIS TROUBLE" section below. |
| 68 |
|
| 69 |
8. Please only use "read(255)" unless you've tested other reading methods. |
| 70 |
There have been reports of dropped characters using other functions. |
| 71 |
|
| 72 |
See the NOTES and KNOWN LIMITATIONS in the SerialPort documentation. The |
| 73 |
".pod" is embedded in the ".pm". The comments on "-w" and "use strict" |
| 74 |
are especially relevant when you start calling this module from your own |
| 75 |
code. Special thanks to Joe Doss for the initial porting. And to Bruce |
| 76 |
Winter for the "required *.ph" list. Also thanks to the others who have |
| 77 |
contributed comments and suggestions. Thanks to Aaron Botsis for letting |
| 78 |
me play with his OpenBSD box and watching DTR lights for me. |
| 79 |
|
| 80 |
FILES: |
| 81 |
|
| 82 |
README - this file |
| 83 |
INSTALL - bare minimum instructions for installing |
| 84 |
TODO - list of other stuff in need of coding |
| 85 |
COPYING - software license |
| 86 |
Changes - for history lovers |
| 87 |
Makefile.PL - the "starting point" for traditional reasons |
| 88 |
configure - used to find the correct headers for SerialPort.xs |
| 89 |
config.h.in - used to build config.h, used by SerialPort.xs |
| 90 |
MANIFEST - distribution file list |
| 91 |
SerialPort.pm - the reason you're reading this |
| 92 |
SerialPort.xs - the C code to get all the serial bits from .h files |
| 93 |
modemtest - quick tool for checking on serial port |
| 94 |
show-tiocm.c.test - simple C tool to report TIOCM* hacks |
| 95 |
Device-SerialPort.spec - RPM .spec file for building RPMS |
| 96 |
|
| 97 |
t - test directory |
| 98 |
t/Altport.pm - stub for inheritance test |
| 99 |
t/01timing.t - tests millisecond counter in "get_tick_count" |
| 100 |
t/test1.t - tests basic port function |
| 101 |
t/test2.t - tests restarting_a_configuration and timeouts |
| 102 |
t/test3.t - Inheritance and export version of test1.t |
| 103 |
t/test4.t - Inheritance version of test2.t and "restart" |
| 104 |
|
| 105 |
eg/any_os.plx - cross-platform "conditional use" demo |
| 106 |
eg/demo1.plx - talks to a "really dumb" terminal |
| 107 |
eg/demo2.plx - "poor man's" readline and chatV |
| 108 |
eg/demo3.plx - looks like a setup menu - but only looks :-( |
| 109 |
eg/demo4.plx - simplest setup: "new", "required param" |
| 110 |
eg/demo5.plx - "waitfor" and "nextline" using lookfor |
| 111 |
eg/demo6.plx - basic tied FileHandle operations, record separators |
| 112 |
eg/demo7.plx - a Perl/Tk based terminal, event loop and callbacks |
| 113 |
eg/demo8.plx - command line terminal emulator with Term::Readkey |
| 114 |
eq/options.plx - post-install test that prints available options |
| 115 |
eg/example1.txt - examples from The Perl Journal #13 |
| 116 |
eg/example2.txt - (minimal mods for cross-platform use) |
| 117 |
eg/example3.txt |
| 118 |
eg/example4.txt |
| 119 |
eg/example5.txt |
| 120 |
eg/example6.txt |
| 121 |
eg/example7.txt |
| 122 |
eg/example8.txt |
| 123 |
|
| 124 |
autotools/* - various tools used by the "configure" script |
| 125 |
|
| 126 |
INSTALL and TEST: |
| 127 |
|
| 128 |
You will need suitable permissions to open the port. If the port is also |
| 129 |
used for logins, you will need to create a lockfile (/var/lock/LCK..ttyS0) |
| 130 |
on my Redhat 5.2 system. Just touch it, the contents are not important. |
| 131 |
They may be someday. But not yet. You might need to be "root" for that. |
| 132 |
|
| 133 |
Run 'perl Makefile.PL' followed by 'make'. This will create install files |
| 134 |
and directories. Run 'make test' with nothing connected to "/dev/ttyS1". |
| 135 |
This will run the tests and create a configuration_file. You can specify |
| 136 |
a different port to test via 'perl Makefile.PL TESTPORT=<DEVICE>'. |
| 137 |
Makefile.PL creates "t/DefaultPort.pm". You can also specify an alternate |
| 138 |
port with the Shell Variable "Makefile_Test_Port". |
| 139 |
|
| 140 |
The Benchmark routines are used to generate reports. The test suite |
| 141 |
covers many of the module methods and sets the port for 9600 baud, |
| 142 |
1 stop, 8 data, no parity, no handshaking, and other defaults. At |
| 143 |
various points in the testing, it expects unconnected CTS and DTR lines. |
| 144 |
The module should restore any port settings on exit. But this has not |
| 145 |
been exhaustively tested yet. |
| 146 |
|
| 147 |
Tests may also be run individually by typing: |
| 148 |
'perl test?.t Page_Delay [/dev/ttySx]' |
| 149 |
|
| 150 |
With no delay, the tests execute too rapidly to follow from a command |
| 151 |
line. Delay may be set from 0 to 5 seconds. |
| 152 |
|
| 153 |
All tests are expected to pass - I would be very interested in hearing |
| 154 |
about failures ("not ok"). These tests should be run from a command |
| 155 |
prompt. For details run "make test TEST_VERBOSE=1". |
| 156 |
|
| 157 |
SOLARIS TROUBLE: |
| 158 |
|
| 159 |
The big problem is with Solaris' handling of DTR. |
| 160 |
|
| 161 |
Depending on hardware, patchlevel, or something very mystical, if |
| 162 |
you have an "se" or "zs" serial port (run "modinfo | grep serial" |
| 163 |
to find out), you may need to correct this DTR bug by adding a |
| 164 |
line to your /etc/system file. See below... |
| 165 |
|
| 166 |
From the following URL: |
| 167 |
http://www.stokely.com/unix.serial.port.resources/tutorials.html |
| 168 |
|
| 169 |
DTR Delay Problems: By default, Suns have a three second |
| 170 |
delay in toggling dtr. If your Sun has a zs serial port you |
| 171 |
can set the variable default_dtrlow to control the number of |
| 172 |
seconds of the delay. If the variable is set to zero, dtr |
| 173 |
can be toggled many times a second. For example, in |
| 174 |
/etc/system add the line "set zs:default_dtrlow = 1" to have |
| 175 |
a 1 second delay. |
| 176 |
|
| 177 |
If your workstation has an se serial port, the /etc/system |
| 178 |
line should be "set se:se_default_dtrlow = 1". However, in |
| 179 |
initial versions of the se driver, the delay was the value |
| 180 |
of (se_default_dtrlow + 1) seconds. If you have this version |
| 181 |
of the se driver, don't set the value to -1 in /etc/system or |
| 182 |
the port will hang on open. If you need to toggle dtr quickly, |
| 183 |
you can still set the value to -1 after the terminal is |
| 184 |
opened by using adb to set the variable manually. |
| 185 |
|
| 186 |
All this is Sun bugid 4230310, fixed by patch 105924-09 or |
| 187 |
higher. The patch makes se_default_dtrlow behave like |
| 188 |
default_dtrlow (i.e. setting se_default_dtrlow to 0 will allow |
| 189 |
rapid toggling of dtr instead of once per second). |
| 190 |
|
| 191 |
So, since I have zs serial ports on my Sun, I added the line: |
| 192 |
|
| 193 |
set zs:default_dtrlow=0 |
| 194 |
|
| 195 |
so I could toggle the DTR rapidly. |
| 196 |
|
| 197 |
There are also problems with "tcdrain" never returning if there |
| 198 |
is no device attached to the serial port. This has been worked |
| 199 |
around in the tests. |
| 200 |
|
| 201 |
|
| 202 |
DEMO PROGRAMS: |
| 203 |
|
| 204 |
Connect a dumb terminal (or a PC that acts like one) to /dev/ttyS0 and |
| 205 |
setup the equivalent configuration. Starting demo1.plx should print a |
| 206 |
three line message on both the terminal and the command line. The |
| 207 |
terminal keyboard (only) now accepts characters which it prints to both |
| 208 |
screens until a CONTROL-Z is typed. Also included is demo2.plx - a truly |
| 209 |
minimal chat program. Bi-directional communication without an event loop, |
| 210 |
sockets, pipes (or much utility ;-) This one uses CAPITAL-Q from the |
| 211 |
active keyboard to quit since <STDIN> doesn't like CONTROL-Z. |
| 212 |
|
| 213 |
AltPort.pm and test3.t implement the "basic Inheritance test" discussed |
| 214 |
in perltoot and other documentation. It also imports the :PARAM constants. |
| 215 |
It's otherwise only slightly modified from test1.t (you'll get a different |
| 216 |
"alias" in test3.t). |
| 217 |
|
| 218 |
Run options.plx to see the available choices for various parameters |
| 219 |
along with the current values. If you have trouble, I will probably |
| 220 |
ask you to save the output of options.plx in a file and send it to me. |
| 221 |
You can specify a port name for options.plx on the command line |
| 222 |
(e.g. 'perl options.plx COM2'). |
| 223 |
|
| 224 |
You can read (many of the important) settings with demo3.plx. If you |
| 225 |
give it a (valid) configuration file on the command line, it will open |
| 226 |
the port with those parameters - so you can test simple changes: see |
| 227 |
the parity example at the end of demo3.plx. |
| 228 |
|
| 229 |
Demo4.plx is a "minimum" script showing just the basics needed to get |
| 230 |
started. |
| 231 |
|
| 232 |
Demo5.plx demonstrates various uses of the lookfor routine including |
| 233 |
setups for "waitfor" and a primitive "readline". Try them out. The |
| 234 |
default "stty" settings work with a VT-100 style terminal. You may |
| 235 |
have to set the options by hand. Use any editor. Let me know if the |
| 236 |
descriptions in the documentation are useable. And if any more options |
| 237 |
are necessary. |
| 238 |
|
| 239 |
Demo6.plx demonstrates tied FileHandles. Perl 5.005 is recommended. |
| 240 |
It "requires" 5.004. It implements timeouts on all user inputs - so |
| 241 |
you can run it "hands-off" to see what happens. |
| 242 |
|
| 243 |
Demo7.plx uses Tk to create a terminal emulator. Its included to show |
| 244 |
polling and callbacks using an event loop. |
| 245 |
|
| 246 |
Demo8.plx is a simple command-line terminal emulator contributed by |
| 247 |
Andrej Mikus. |
| 248 |
|
| 249 |
The Perl Journal #13 included an article on Controlling a Modem with |
| 250 |
Win32::SerialPort. Slightly revised versions of all the Examples |
| 251 |
from the article are included in the "eg" subdirectory. The revisions |
| 252 |
cover cross-platform use and workarounds for small timing differences. |
| 253 |
|
| 254 |
Please tell me what does and what doesn't work. The module has proven |
| 255 |
to be pretty robust. But I can't test all possible configurations. |
| 256 |
Don't trust it for anything important without complete testing. |
| 257 |
|
| 258 |
And watch for updates at: |
| 259 |
|
| 260 |
%%%% http://sendpage.org/device-serialport/ |
| 261 |
|
| 262 |
or CPAN under authors/id/C/CO/COOK or Device::SerialPort |
| 263 |
|
| 264 |
Thanks, |
| 265 |
|
| 266 |
-Kees <[email protected]> |
| 267 |
|
| 268 |
Copyright (C) 1999, Bill Birthisel. All rights reserved. |
| 269 |
Copyright (C) 2001-2005 Kees Cook. All rights reserved. |
| 270 |
This module is free software; you can redistribute it and/or modify it under |
| 271 |
the same terms as Perl itself. |