Debian Codegraph @

README

raw
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.