Device::SerialPort VERSION=0.21, 2003 Jun 12 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. 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: 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 README - this file 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 - simple C tool to report TIOCM* hacks t - test directory t/Altport.pm - stub for inheritance test t/test1.t - RUN ME FIRST, basic tests 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/ttyS0". This will run the tests and create a configuration_file. You can specify a different port to test via 'perl Makefile.PL PORT'. 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. 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 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 Copyright (C) 1999, Bill Birthisel. All rights reserved. Copyright (C) 2001-2003 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.