1Device::SerialPort 2 3Hello Serial Port users: 4 5If you are running Windows 95 or later, you want the Win32::SerialPort 6module instead of this one. It has a compatible user interface. 7Available from your favorite CPAN site. Since someone asked, there is 8not currently an equivalent for MS-DOS (and none is anticipated). 9 10This is a POSIX-based version of the Win32::Serialport module ported by 11Joe Doss for the MisterHouse Home Automation Package from Version 0.08 12of the Win32 module. He replaced calls to the Win32 API with similar 13functions implemented using POSIX calls. While most of the testing has 14occurred on linux, the package should work on other POSIX-compliant 15Operating Systems. 16 17Most of the functions from Win32::SerialPort are now available. Almost 18all the demos and examples work with minimal modifications. Many of the 19methods are new with this release or 0.06, so expect a few bugs and 20consider everything experimental. But the intent is to "clone" the 21corresponding features of the Win32::SerialPort module whenever 22practical - see the documentation for that module as well as this one 23for details. 24 25Version 0.07 improved the lockfile support, added some application 26variables that are saved in the configuration_file, and added the 27ioctl-based methods status, modemlines, and write_done. These act 28mostly like their Win32 cousins. Since they use ioctls, they are 29only available on systems that "can_ioctl". 30 31Version 0.09 adds further compatibility for other OSes, including AIX, 32Solaris, and OpenBSD. Kees Cook is now maintaining this code for use 33with the Sendpage tool (http://sendpage.org/). 34 35Version 0.20 uses XS to figure out the serial/modem bits needed to do 36all the state fiddling. Pay close attention to the "configure" output 37warnings to find out about possible broken things on your system. 38 39Version 1.0.0 changes the version number scheme to be like Perl itself. 40 41COMPATIBILITY NOTES: 42 431. 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 472. 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 543. 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 584. The save, start, and restart methods are now supported. The format of 59 the configuration_file is not identical to the Win32 one. 60 615. 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 646. Right now, AIX will also fail some of the tests, including setting 65 hardware flow control. I'm working on fixing this. 66 677. For Solaris, see the "SOLARIS TROUBLE" section below. 68 698. Please only use "read(255)" unless you've tested other reading methods. 70 There have been reports of dropped characters using other functions. 71 72See the NOTES and KNOWN LIMITATIONS in the SerialPort documentation. The 73".pod" is embedded in the ".pm". The comments on "-w" and "use strict" 74are especially relevant when you start calling this module from your own 75code. Special thanks to Joe Doss for the initial porting. And to Bruce 76Winter for the "required *.ph" list. Also thanks to the others who have 77contributed comments and suggestions. Thanks to Aaron Botsis for letting 78me play with his OpenBSD box and watching DTR lights for me. 79 80FILES: 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 126INSTALL and TEST: 127 128You will need suitable permissions to open the port. If the port is also 129used for logins, you will need to create a lockfile (/var/lock/LCK..ttyS0) 130on my Redhat 5.2 system. Just touch it, the contents are not important. 131They may be someday. But not yet. You might need to be "root" for that. 132 133Run 'perl Makefile.PL' followed by 'make'. This will create install files 134and directories. Run 'make test' with nothing connected to "/dev/ttyS1". 135This will run the tests and create a configuration_file. You can specify 136a different port to test via 'perl Makefile.PL TESTPORT=<DEVICE>'. 137Makefile.PL creates "t/DefaultPort.pm". You can also specify an alternate 138port with the Shell Variable "Makefile_Test_Port". 139 140The Benchmark routines are used to generate reports. The test suite 141covers many of the module methods and sets the port for 9600 baud, 1421 stop, 8 data, no parity, no handshaking, and other defaults. At 143various points in the testing, it expects unconnected CTS and DTR lines. 144The module should restore any port settings on exit. But this has not 145been exhaustively tested yet. 146 147Tests may also be run individually by typing: 148 'perl test?.t Page_Delay [/dev/ttySx]' 149 150With no delay, the tests execute too rapidly to follow from a command 151line. Delay may be set from 0 to 5 seconds. 152 153All tests are expected to pass - I would be very interested in hearing 154about failures ("not ok"). These tests should be run from a command 155prompt. For details run "make test TEST_VERBOSE=1". 156 157SOLARIS 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 202DEMO PROGRAMS: 203 204Connect a dumb terminal (or a PC that acts like one) to /dev/ttyS0 and 205setup the equivalent configuration. Starting demo1.plx should print a 206three line message on both the terminal and the command line. The 207terminal keyboard (only) now accepts characters which it prints to both 208screens until a CONTROL-Z is typed. Also included is demo2.plx - a truly 209minimal chat program. Bi-directional communication without an event loop, 210sockets, pipes (or much utility ;-) This one uses CAPITAL-Q from the 211active keyboard to quit since <STDIN> doesn't like CONTROL-Z. 212 213AltPort.pm and test3.t implement the "basic Inheritance test" discussed 214in perltoot and other documentation. It also imports the :PARAM constants. 215It's otherwise only slightly modified from test1.t (you'll get a different 216"alias" in test3.t). 217 218Run options.plx to see the available choices for various parameters 219along with the current values. If you have trouble, I will probably 220ask you to save the output of options.plx in a file and send it to me. 221You can specify a port name for options.plx on the command line 222(e.g. 'perl options.plx COM2'). 223 224You can read (many of the important) settings with demo3.plx. If you 225give it a (valid) configuration file on the command line, it will open 226the port with those parameters - so you can test simple changes: see 227the parity example at the end of demo3.plx. 228 229Demo4.plx is a "minimum" script showing just the basics needed to get 230started. 231 232Demo5.plx demonstrates various uses of the lookfor routine including 233setups for "waitfor" and a primitive "readline". Try them out. The 234default "stty" settings work with a VT-100 style terminal. You may 235have to set the options by hand. Use any editor. Let me know if the 236descriptions in the documentation are useable. And if any more options 237are necessary. 238 239Demo6.plx demonstrates tied FileHandles. Perl 5.005 is recommended. 240It "requires" 5.004. It implements timeouts on all user inputs - so 241you can run it "hands-off" to see what happens. 242 243Demo7.plx uses Tk to create a terminal emulator. Its included to show 244polling and callbacks using an event loop. 245 246Demo8.plx is a simple command-line terminal emulator contributed by 247Andrej Mikus. 248 249The Perl Journal #13 included an article on Controlling a Modem with 250Win32::SerialPort. Slightly revised versions of all the Examples 251from the article are included in the "eg" subdirectory. The revisions 252cover cross-platform use and workarounds for small timing differences. 253 254Please tell me what does and what doesn't work. The module has proven 255to be pretty robust. But I can't test all possible configurations. 256Don't trust it for anything important without complete testing. 257 258And watch for updates at: 259 260%%%% http://sendpage.org/device-serialport/ 261 262or CPAN under authors/id/C/CO/COOK or Device::SerialPort 263 264Thanks, 265 266-Kees <kees@outflux.net> 267 268Copyright (C) 1999, Bill Birthisel. All rights reserved. 269Copyright (C) 2001-2005 Kees Cook. All rights reserved. 270This module is free software; you can redistribute it and/or modify it under 271the same terms as Perl itself. 272