1SerialPort(3) User Contributed Perl Documentation SerialPort(3)
2
6 Device::SerialPort - Linux/POSIX emulation of Win32::SerialPort
7 functions.
8
10 use Device::SerialPort qw( :PARAM :STAT 0.07 );
11 Constructors
13 # $lockfile is optional
14 $PortObj = new Device::SerialPort ($PortName, $quiet, $lockfile)
15 || die "Can't open $PortName: $!\n";
16 $PortObj = start Device::SerialPort ($Configuration_File_Name)
18 || die "Can't start $Configuration_File_Name: $!\n";
19 $PortObj = tie (*FH, 'Device::SerialPort', $Configuration_File_Name)
21 || die "Can't tie using $Configuration_File_Name: $!\n";
22 Configuration Utility Methods
24 $PortObj->alias("MODEM1");
25 $PortObj->save($Configuration_File_Name)
27 || warn "Can't save $Configuration_File_Name: $!\n";
28 # currently optional after new, POSIX version expected to succeed
30 $PortObj->write_settings;
31 # rereads file to either return open port to a known state
33 # or switch to a different configuration on the same port
34 $PortObj->restart($Configuration_File_Name)
35 || warn "Can't reread $Configuration_File_Name: $!\n";
36 # "app. variables" saved in $Configuration_File, not used internally
38 $PortObj->devicetype('none'); # CM11, CM17, 'weeder', 'modem'
39 $PortObj->hostname('localhost'); # for socket-based implementations
40 $PortObj->hostaddr(0); # false unless specified
41 $PortObj->datatype('raw'); # in case an application needs_to_know
42 $PortObj->cfg_param_1('none'); # null string '' hard to save/restore
43 $PortObj->cfg_param_2('none'); # 3 spares should be enough for now
44 $PortObj->cfg_param_3('none'); # one may end up as a log file path
45 # test suite use only
47 @necessary_param = Device::SerialPort->set_test_mode_active(1);
48 # exported by :PARAM
50 nocarp || carp "Something fishy";
51 $a = SHORTsize; # 0xffff
52 $a = LONGsize; # 0xffffffff
53 $answer = yes_true("choice"); # 1 or 0
54 OS_Error unless ($API_Call_OK); # prints error
55 Configuration Parameter Methods
57 # most methods can be called two ways:
58 $PortObj->handshake("xoff"); # set parameter
59 $flowcontrol = $PortObj->handshake; # current value (scalar)
60 # The only "list context" method calls from Win32::SerialPort
62 # currently supported are those for baudrate, parity, databits,
63 # stopbits, and handshake (which only accept specific input values).
64 @handshake_opts = $PortObj->handshake; # permitted choices (list)
65 # similar
67 $PortObj->baudrate(9600);
68 $PortObj->parity("odd");
69 $PortObj->databits(8);
70 $PortObj->stopbits(1); # POSIX does not support 1.5 stopbits
71 # these are essentially dummies in POSIX implementation
73 # the calls exist to support compatibility
74 $PortObj->buffers(4096, 4096); # returns (4096, 4096)
75 @max_values = $PortObj->buffer_max; # returns (4096, 4096)
76 $PortObj->reset_error; # returns 0
77 # true/false parameters (return scalar context only)
79 # parameters exist, but message processing not yet fully implemented
80 $PortObj->user_msg(ON); # built-in instead of warn/die above
81 $PortObj->error_msg(ON); # translate error bitmasks and carp
82 $PortObj->parity_enable(F); # faults during input
84 $PortObj->debug(0);
85 # true/false capabilities (read only)
87 # most are just constants in the POSIX case
88 $PortObj->can_baud; # 1
89 $PortObj->can_databits; # 1
90 $PortObj->can_stopbits; # 1
91 $PortObj->can_dtrdsr; # 1
92 $PortObj->can_handshake; # 1
93 $PortObj->can_parity_check; # 1
94 $PortObj->can_parity_config; # 1
95 $PortObj->can_parity_enable; # 1
96 $PortObj->can_rlsd; # 0 currently
97 $PortObj->can_16bitmode; # 0 Win32-specific
98 $PortObj->is_rs232; # 1
99 $PortObj->is_modem; # 0 Win32-specific
100 $PortObj->can_rtscts; # 1
101 $PortObj->can_xonxoff; # 1
102 $PortObj->can_xon_char; # 1 use stty
103 $PortObj->can_spec_char; # 0 use stty
104 $PortObj->can_interval_timeout; # 0 currently
105 $PortObj->can_total_timeout; # 1 currently
106 $PortObj->can_ioctl; # automatically detected
107 $PortObj->can_status; # automatically detected
108 $PortObj->can_write_done; # automatically detected
109 $PortObj->can_modemlines; # automatically detected
110 $PortObj->can_wait_modemlines;# automatically detected
111 $PortObj->can_intr_count; # automatically detected
112 $PortObj->can_arbitrary_baud; # automatically detected
113 Operating Methods
115 ($count_in, $string_in) = $PortObj->read($InBytes);
116 warn "read unsuccessful\n" unless ($count_in == $InBytes);
117 $count_out = $PortObj->write($output_string);
119 warn "write failed\n" unless ($count_out);
120 warn "write incomplete\n" if ( $count_out != length($output_string) );
121 if ($string_in = $PortObj->input) { PortObj->write($string_in); }
123 # simple echo with no control character processing
124 if ($PortObj->can_wait_modemlines) {
126 $rc = $PortObj->wait_modemlines( MS_RLSD_ON );
127 if (!$rc) { print "carrier detect changed\n"; }
128 }
129 if ($PortObj->can_modemlines) {
131 $ModemStatus = $PortObj->modemlines;
132 if ($ModemStatus & $PortObj->MS_RLSD_ON) { print "carrier detected\n"; }
133 }
134 if ($PortObj->can_intr_count) {
136 $count = $PortObj->intr_count();
137 print "got $count interrupts\n";
138 }
139 if ($PortObj->can_arbitrary_baud) {
141 print "this port can set arbitrary baud rates\n";
142 }
143 ($BlockingFlags, $InBytes, $OutBytes, $ErrorFlags) = $PortObj->status;
145 # same format for compatibility. Only $InBytes and $OutBytes are
146 # currently returned (on linux). Others are 0.
147 # Check return value of "can_status" to see if this call is valid.
148 ($done, $count_out) = $PortObj->write_done(0);
150 # POSIX defaults to background write. Currently $count_out always 0.
151 # $done set when hardware finished transmitting and shared line can
152 # be released for other use. Ioctl may not work on all OSs.
153 # Check return value of "can_write_done" to see if this call is valid.
154 $PortObj->write_drain; # POSIX alternative to Win32 write_done(1)
156 # set when software is finished transmitting
157 $PortObj->purge_all;
158 $PortObj->purge_rx;
159 $PortObj->purge_tx;
160 # controlling outputs from the port
162 $PortObj->dtr_active(T); # sends outputs direct to hardware
163 $PortObj->rts_active(Yes); # return status of ioctl call
164 # return undef on failure
165 $PortObj->pulse_break_on($milliseconds); # off version is implausible
167 $PortObj->pulse_rts_on($milliseconds);
168 $PortObj->pulse_rts_off($milliseconds);
169 $PortObj->pulse_dtr_on($milliseconds);
170 $PortObj->pulse_dtr_off($milliseconds);
171 # sets_bit, delays, resets_bit, delays
172 # returns undef if unsuccessful or ioctls not implemented
173 $PortObj->read_const_time(100); # const time for read (milliseconds)
175 $PortObj->read_char_time(5); # avg time between read char
176 $milliseconds = $PortObj->get_tick_count;
178 Methods used with Tied FileHandles
180 $PortObj = tie (*FH, 'Device::SerialPort', $Configuration_File_Name)
181 || die "Can't tie: $!\n"; ## TIEHANDLE ##
182 print FH "text"; ## PRINT ##
184 $char = getc FH; ## GETC ##
185 syswrite FH, $out, length($out), 0; ## WRITE ##
186 $line = <FH>; ## READLINE ##
187 @lines = <FH>; ## READLINE ##
188 printf FH "received: %s", $line; ## PRINTF ##
189 read (FH, $in, 5, 0) or die "$!"; ## READ ##
190 sysread (FH, $in, 5, 0) or die "$!"; ## READ ##
191 close FH || warn "close failed"; ## CLOSE ##
192 undef $PortObj;
193 untie *FH; ## DESTROY ##
194 $PortObj->linesize(10); # with READLINE
196 $PortObj->lastline("_GOT_ME_"); # with READLINE, list only
197 ## with PRINT and PRINTF, return previous value of separator
199 $old_ors = $PortObj->output_record_separator("RECORD");
200 $old_ofs = $PortObj->output_field_separator("COMMA");
201 Destructors
203 $PortObj->close || warn "close failed";
204 # release port to OS - needed to reopen
205 # close will not usually DESTROY the object
206 # also called as: close FH || warn "close failed";
207 undef $PortObj;
209 # preferred unless reopen expected since it triggers DESTROY
210 # calls $PortObj->close but does not confirm success
211 # MUST precede untie - do all three IN THIS SEQUENCE before re-tie.
212 untie *FH;
214 Methods for I/O Processing
216 $PortObj->are_match("text", "\n"); # possible end strings
217 $PortObj->lookclear; # empty buffers
218 $PortObj->write("Feed Me:"); # initial prompt
219 $PortObj->is_prompt("More Food:"); # not implemented
220 my $gotit = "";
222 until ("" ne $gotit) {
223 $gotit = $PortObj->lookfor; # poll until data ready
224 die "Aborted without match\n" unless (defined $gotit);
225 sleep 1; # polling sample time
226 }
227 printf "gotit = %s\n", $gotit; # input BEFORE the match
229 my ($match, $after, $pattern, $instead) = $PortObj->lastlook;
230 # input that MATCHED, input AFTER the match, PATTERN that matched
231 # input received INSTEAD when timeout without match
232 printf "lastlook-match = %s -after = %s -pattern = %s\n",
233 $match, $after, $pattern;
234 $gotit = $PortObj->lookfor($count); # block until $count chars received
236 $PortObj->are_match("-re", "pattern", "text");
238 # possible match strings: "pattern" is a regular expression,
239 # "text" is a literal string
240
242 This module provides an object-based user interface essentially
243 identical to the one provided by the Win32::SerialPort module.
244 Initialization
246 The primary constructor is new with either a PortName, or a
247 Configuretion File specified. With a PortName, this will open the port
248 and create the object. The port is not yet ready for read/write access.
249 First, the desired parameter settings must be established. Since these
250 are tuning constants for an underlying hardware driver in the Operating
251 System, they are all checked for validity by the methods that set them.
252 The write_settings method updates the port (and will return True under
253 POSIX). Ports are opened for binary transfers. A separate "binmode" is
254 not needed.
255 $PortObj = new Device::SerialPort ($PortName, $quiet, $lockfile)
257 || die "Can't open $PortName: $!\n";
258 The $quiet parameter is ignored and is only there for compatibility
260 with Win32::SerialPort. The $lockfile parameter is optional. It will
261 attempt to create a file (containing just the current process id) at
262 the location specified. This file will be automatically deleted when
263 the $PortObj is no longer used (by DESTROY). You would usually request
264 $lockfile with $quiet true to disable messages while attempting to
265 obtain exclusive ownership of the port via the lock. Lockfiles are
266 experimental in Version 0.07. They are intended for use with other
267 applications. No attempt is made to resolve port aliases (/dev/modem ==
268 /dev/ttySx) or to deal with login processes such as getty and uugetty.
269 Using a Configuration File with new or by using second constructor,
271 start, scripts can be simplified if they need a constant setup. It
272 executes all the steps from new to write_settings based on a previously
273 saved configuration. This constructor will return "undef" on a bad
274 configuration file or failure of a validity check. The returned object
275 is ready for access. This is new and experimental for Version 0.055.
276 $PortObj2 = start Device::SerialPort ($Configuration_File_Name)
278 || die;
279 The third constructor, tie, will combine the start with Perl's support
281 for tied FileHandles (see perltie). Device::SerialPort will implement
282 the complete set of methods: TIEHANDLE, PRINT, PRINTF, WRITE, READ,
283 GETC, READLINE, CLOSE, and DESTROY. Tied FileHandle support is new with
284 Version 0.04 and the READ and READLINE methods were added in Version
285 0.06. In "scalar context", READLINE sets stty_icanon to do character
286 processing and calls lookfor. It restores stty_icanon after the read.
287 In "list context", READLINE does Canonical (line) reads if stty_icanon
288 is set or calls streamline if it is not. (stty_icanon is not altered).
289 The streamline choice allows duplicating the operation of
290 Win32::SerialPort for cross-platform scripts.
291 The implementation attempts to mimic STDIN/STDOUT behaviour as closely
293 as possible: calls block until done and data strings that exceed
294 internal buffers are divided transparently into multiple calls. In
295 Version 0.06, the output separators $, and "$\" are also applied to
296 PRINT if set. The output_record_separator and output_field_separator
297 methods can set Port-FileHandle-Specific versions of $, and "$\" if
298 desired. Since PRINTF is treated internally as a single record PRINT,
299 "$\" will be applied. Output separators are not applied to WRITE
300 (called as "syswrite FH, $scalar, $length, [$offset]"). The
301 input_record_separator $/ is not explicitly supported - but an
302 identical function can be obtained with a suitable are_match setting.
303 $PortObj2 = tie (*FH, 'Device::SerialPort', $Configuration_File_Name)
305 || die;
306 The tied FileHandle methods may be combined with the Device::SerialPort
308 methods for read, input, and write as well as other methods. The
309 typical restrictions against mixing print with syswrite do not apply.
310 Since both (tied) read and sysread call the same "$ob->READ" method,
311 and since a separate "$ob->read" method has existed for some time in
312 Device::SerialPort, you should always use sysread with the tied
313 interface (when it is implemented).
314 Certain parameters SHOULD be set before executing
316 write_settings. Others will attempt to deduce defaults from
317 the hardware or from other parameters. The Required parameters
318 are:
319 baudrate
321 Any legal value.
323 parity
325 One of the following: "none", "odd", "even".
327 By default, incoming parity is not checked. This mimics the
329 behavior of most terminal programs (like "minicom"). If you
330 need parity checking enabled, please use the "stty_inpck" and
331 "stty_istrip" functions.
332 databits
334 An integer from 5 to 8.
336 stopbits
338 Legal values are 1 and 2.
340 handshake
342 One of the following: "none", "rts", "xoff".
344 Some individual parameters (eg. baudrate) can be changed after the
346 initialization is completed. These will be validated and will update
347 the serial driver as required. The save method will write the current
348 parameters to a file that start, tie, and restart can use to
349 reestablish a functional setup.
350 $PortObj = new Win32::SerialPort ($PortName, $quiet)
352 || die "Can't open $PortName: $^E\n"; # $quiet is optional
353 $PortObj->user_msg(ON);
355 $PortObj->databits(8);
356 $PortObj->baudrate(9600);
357 $PortObj->parity("none");
358 $PortObj->stopbits(1);
359 $PortObj->handshake("rts");
360 $PortObj->write_settings || undef $PortObj;
362 $PortObj->save($Configuration_File_Name);
364 $PortObj->baudrate(300);
365 $PortObj->restart($Configuration_File_Name); # back to 9600 baud
366 $PortObj->close || die "failed to close";
368 undef $PortObj; # frees memory back to perl
369 Configuration Utility Methods
371 Use alias to convert the name used by "built-in" messages.
372 $PortObj->alias("MODEM1");
374 Starting in Version 0.07, a number of Application Variables are saved
376 in $Configuration_File. These parameters are not used internally. But
377 methods allow setting and reading them. The intent is to facilitate the
378 use of separate configuration scripts to create the files. Then an
379 application can use start as the Constructor and not bother with
380 command line processing or managing its own small configuration file.
381 The default values and number of parameters is subject to change.
382 $PortObj->devicetype('none');
384 $PortObj->hostname('localhost'); # for socket-based implementations
385 $PortObj->hostaddr(0); # a "false" value
386 $PortObj->datatype('raw'); # 'record' is another possibility
387 $PortObj->cfg_param_1('none');
388 $PortObj->cfg_param_2('none'); # 3 spares should be enough for now
389 $PortObj->cfg_param_3('none');
390 Configuration and Capability Methods
392 The Win32 Serial Comm API provides extensive information concerning the
393 capabilities and options available for a specific port (and instance).
394 This module will return suitable responses to facilitate porting code
395 from that environment.
396 The get_tick_count method is a clone of the Win32::GetTickCount()
398 function. It matches a corresponding method in Win32::CommPort. It
399 returns time in milliseconds - but can be used in cross-platform
400 scripts.
401 Binary selections will accept as true any of the following:
403 "("YES", "Y", "ON", "TRUE", "T", "1", 1)" (upper/lower/mixed
404 case) Anything else is false.
405 There are a large number of possible configuration and option
407 parameters. To facilitate checking option validity in scripts,
408 most configuration methods can be used in two different ways:
409 method called with an argument
411 The parameter is set to the argument, if valid. An invalid
413 argument returns false (undef) and the parameter is unchanged.
414 The function will also carp if $user_msg is true. The port will
415 be updated immediately if allowed (an automatic write_settings
416 is called).
417 method called with no argument in scalar context
419 The current value is returned. If the value is not initialized
421 either directly or by default, return "undef" which will parse
422 to false. For binary selections (true/false), return the
423 current value. All current values from "multivalue" selections
424 will parse to true.
425 method called with no argument in list context
427 Methods which only accept a limited number of specific input
429 values return a list consisting of all acceptable choices. The
430 null list "(undef)" will be returned for failed calls in list
431 context (e.g. for an invalid or unexpected argument). Only the
432 baudrate, parity, databits, stopbits, and handshake methods
433 currently support this feature.
434 Operating Methods
436 Version 0.04 adds pulse methods for the RTS, BREAK, and DTR bits. The
437 pulse methods assume the bit is in the opposite state when the method
438 is called. They set the requested state, delay the specified number of
439 milliseconds, set the opposite state, and again delay the specified
440 time. These methods are designed to support devices, such as the X10
441 "FireCracker" control and some modems, which require pulses on these
442 lines to signal specific events or data. Timing for the active part of
443 pulse_break_on is handled by POSIX::tcsendbreak(0), which sends a
444 250-500 millisecond BREAK pulse. It is NOT guaranteed to block until
445 done.
446 $PortObj->pulse_break_on($milliseconds);
448 $PortObj->pulse_rts_on($milliseconds);
449 $PortObj->pulse_rts_off($milliseconds);
450 $PortObj->pulse_dtr_on($milliseconds);
451 $PortObj->pulse_dtr_off($milliseconds);
452 In Version 0.05, these calls and the rts_active and dtr_active calls
454 verify the parameters and any required ioctl constants, and return
455 "undef" unless the call succeeds. You can use the can_ioctl method to
456 see if the required constants are available. On Version 0.04, the
457 module would not load unless asm/termios.ph was found at startup.
458 Stty Shortcuts
460 Version 0.06 adds primitive methods to modify port parameters that
461 would otherwise require a "system("stty...");" command. These act much
462 like the identically-named methods in Win32::SerialPort. However, they
463 are initialized from "current stty settings" when the port is opened
464 rather than from defaults. And like stty settings, they are passed to
465 the serial driver and apply to all operations rather than only to I/O
466 processed via the lookfor method or the tied FileHandle methods. Each
467 returns the current setting for the parameter. There are no "global" or
468 "combination" parameters - you still need system("stty...") for that.
469 The methods which handle CHAR parameters set and return values as
471 ord(CHAR). This corresponds to the settings in the POSIX termios
472 cc_field array. You are unlikely to actually want to modify most of
473 these. They reflect the special characters which can be set by stty.
474 $PortObj->is_xon_char($num_char); # VSTART (stty start=.)
476 $PortObj->is_xoff_char($num_char); # VSTOP
477 $PortObj->is_stty_intr($num_char); # VINTR
478 $PortObj->is_stty_quit($num_char); # VQUIT
479 $PortObj->is_stty_eof($num_char); # VEOF
480 $PortObj->is_stty_eol($num_char); # VEOL
481 $PortObj->is_stty_erase($num_char); # VERASE
482 $PortObj->is_stty_kill($num_char); # VKILL
483 $PortObj->is_stty_susp($num_char); # VSUSP
484 Binary settings supported by POSIX will return 0 or 1. Several
486 parameters settable by stty do not yet have shortcut methods. Contact
487 me if you need one that is not supported. These are the common choices.
488 Try "man stty" if you are not sure what they do.
489 $PortObj->stty_echo;
491 $PortObj->stty_echoe;
492 $PortObj->stty_echok;
493 $PortObj->stty_echonl;
494 $PortObj->stty_ignbrk;
495 $PortObj->stty_istrip;
496 $PortObj->stty_inpck;
497 $PortObj->stty_parmrk;
498 $PortObj->stty_ignpar;
499 $PortObj->stty_icrnl;
500 $PortObj->stty_igncr;
501 $PortObj->stty_inlcr;
502 $PortObj->stty_opost;
503 $PortObj->stty_isig;
504 $PortObj->stty_icanon;
505 The following methods require successfully loading ioctl constants.
507 They will return "undef" if the needed constants are not found. But the
508 method calls may still be used without syntax errors or warnings even
509 in that case.
510 $PortObj->stty_ocrlf;
512 $PortObj->stty_onlcr;
513 $PortObj->stty_echoke;
514 $PortObj->stty_echoctl;
515 Lookfor and I/O Processing
517 Some communications programs have a different need - to collect (or
518 discard) input until a specific pattern is detected. For lines, the
519 pattern is a line-termination. But there are also requirements to
520 search for other strings in the input such as "username:" and
521 "password:". The lookfor method provides a consistant mechanism for
522 solving this problem. It searches input character-by-character looking
523 for a match to any of the elements of an array set using the are_match
524 method. It returns the entire input up to the match pattern if a match
525 is found. If no match is found, it returns "" unless an input error or
526 abort is detected (which returns undef).
527 Unlike Win32::SerialPort, lookfor does not handle backspace, echo, and
529 other character processing. It expects the serial driver to handle
530 those and to be controlled via stty. For interacting with humans, you
531 will probably want stty_icanon(1) during lookfor to obtain familiar
532 command-line response. The actual match and the characters after it (if
533 any) may also be viewed using the lastlook method. It also adopts the
534 convention from Expect.pm that match strings are literal text (tested
535 using index) unless preceeded in the are_match list by a "-re", entry.
536 The default are_match list is "("\n")", which matches complete lines.
537 my ($match, $after, $pattern, $instead) = $PortObj->lastlook;
539 # input that MATCHED, input AFTER the match, PATTERN that matched
540 # input received INSTEAD when timeout without match ("" if match)
541 $PortObj->are_match("text1", "-re", "pattern", "text2");
543 # possible match strings: "pattern" is a regular expression,
544 # "text1" and "text2" are literal strings
545 Everything in lookfor is still experimental. Please let me know if you
547 use it (or can't use it), so I can confirm bug fixes don't break your
548 code. For literal strings, $match and $pattern should be identical.
549 The $instead value returns the internal buffer tested by the match
550 logic. A successful match or a lookclear resets it to "" - so it is
551 only useful for error handling such as timeout processing or reporting
552 unexpected responses.
553 The lookfor method is designed to be sampled periodically (polled). Any
555 characters after the match pattern are saved for a subsequent lookfor.
556 Internally, lookfor is implemented using the nonblocking input method
557 when called with no parameter. If called with a count, lookfor calls
558 "$PortObj->read(count)" which blocks until the read is Complete or a
559 Timeout occurs. The blocking alternative should not be used unless a
560 fault time has been defined using read_interval, read_const_time, and
561 read_char_time. It exists mostly to support the tied FileHandle
562 functions sysread, getc, and <FH>. When stty_icanon is active, even the
563 non-blocking calls will not return data until the line is complete.
564 The internal buffers used by lookfor may be purged by the lookclear
566 method (which also clears the last match). For testing, lookclear can
567 accept a string which is "looped back" to the next input. This feature
568 is enabled only when set_test_mode_active(1). Normally, lookclear will
569 return "undef" if given parameters. It still purges the buffers and
570 last_match in that case (but nothing is "looped back"). You will want
571 stty_echo(0) when exercising loopback.
572 The matchclear method is designed to handle the "special case" where
574 the match string is the first character(s) received by lookfor. In this
575 case, "$lookfor_return == """, lookfor does not provide a clear
576 indication that a match was found. The matchclear returns the same
577 $match that would be returned by lastlook and resets it to "" without
578 resetting any of the other buffers. Since the lookfor already searched
579 through the match, matchclear is used to both detect and step-over
580 "blank" lines.
581 The character-by-character processing used by lookfor is fine for
583 interactive activities and tasks which expect short responses. But it
584 has too much "overhead" to handle fast data streams.There is also a
585 streamline method which is a fast, line-oriented alternative with just
586 pattern searching. Since streamline uses the same internal buffers, the
587 lookclear, lastlook, are_match, and matchclear methods act the same in
588 both cases. In fact, calls to streamline and lookfor can be interleaved
589 if desired (e.g. an interactive task that starts an upload and returns
590 to interactive activity when it is complete).
591 There are two additional methods for supporting "list context" input:
593 lastline sets an "end_of_file" Regular Expression, and linesize permits
594 changing the "packet size" in the blocking read operation to allow
595 tuning performance to data characteristics. These two only apply during
596 READLINE. The default for linesize is 1. There is no default for the
597 lastline method.
598 The Regular Expressions set by are_match and lastline will be pre-
600 compiled using the qr// construct on Perl 5.005 and higher. This
601 doubled lookfor and streamline speed in my tests with Regular
602 Expressions - but actual improvements depend on both patterns and input
603 data.
604 The functionality of lookfor includes a limited subset of the
606 capabilities found in Austin Schutz's Expect.pm for Unix (and Tcl's
607 expect which it resembles). The "$before, $match, $pattern, and $after"
608 return values are available if someone needs to create an "expect"
609 subroutine for porting a script. When using multiple patterns, there is
610 one important functional difference: Expect.pm looks at each pattern in
611 turn and returns the first match found; lookfor and streamline test all
612 patterns and return the one found earliest in the input if more than
613 one matches.
614 Exports
616 Nothing is exported by default. The following tags can be used to have
617 large sets of symbols exported:
618 :PARAM
620 Utility subroutines and constants for parameter setting and test:
621 LONGsize SHORTsize nocarp yes_true
623 OS_Error
624 :STAT
626 The Constants named BM_* and CE_* are omitted. But the modem status
627 (MS_*) Constants are defined for possible use with modemlines and
628 wait_modemlines. They are assigned to corresponding functions, but
629 the bit position will be different from that on Win32.
630 Which incoming bits are active:
632 MS_CTS_ON - Clear to send
634 MS_DSR_ON - Data set ready
635 MS_RING_ON - Ring indicator
636 MS_RLSD_ON - Carrier detected
637 MS_RTS_ON - Request to send (might not exist on Win32)
638 MS_DTR_ON - Data terminal ready (might not exist on Win32)
639 If you want to write more POSIX-looking code, you can use the
641 constants seen there, instead of the Win32 versions:
642 TIOCM_CTS, TIOCM_DSR, TIOCM_RI, TIOCM_CD, TIOCM_RTS, and TIOCM_DTR
644 Offsets into the array returned by status:
646 ST_BLOCK ST_INPUT ST_OUTPUT ST_ERROR
648 :ALL
650 All of the above. Except for the test suite, there is not really a
651 good reason to do this.
652
654 Here is a handy pinout map, showing each line and signal on a standard
655 DB9 connector:
656 1 DCD Data Carrier Detect
658 2 RD Receive Data
660 3 TD Transmit Data
662 4 DTR Data Terminal Ready
664 5 SG Signal Ground
666 6 DSR Data Set Ready
668 7 RTS Request to Send
670 8 CTS Clear to Send
672 9 RI Ring Indicator
674
676 The object returned by new is NOT a Filehandle. You will be
677 disappointed if you try to use it as one.
678 e.g. the following is WRONG!!
680 print $PortObj "some text";
682 This module uses POSIX termios extensively. Raw API calls are very
684 unforgiving. You will certainly want to start perl with the -w switch.
685 If you can, use strict as well. Try to ferret out all the syntax and
686 usage problems BEFORE issuing the API calls (many of which modify
687 tuning constants in hardware device drivers....not where you want to
688 look for bugs).
689 With all the options, this module needs a good tutorial. It doesn't
691 have one yet.
692
694 It is recommended to always use "read(255)" due to some unexpected
695 behavior with the termios under some operating systems (Linux and
696 Solaris at least). To deal with this, a routine is usually needed to
697 read from the serial port until you have what you want. This is a
698 quick example of how to do that:
699 my $port=Device::SerialPort->new("/dev/ttyS0");
701 my $STALL_DEFAULT=10; # how many seconds to wait for new input
703 my $timeout=$STALL_DEFAULT;
705 $port->read_char_time(0); # don't wait for each character
707 $port->read_const_time(1000); # 1 second per unfulfilled "read" call
708 my $chars=0;
710 my $buffer="";
711 while ($timeout>0) {
712 my ($count,$saw)=$port->read(255); # will read _up to_ 255 chars
713 if ($count > 0) {
714 $chars+=$count;
715 $buffer.=$saw;
716 # Check here to see if what we want is in the $buffer
718 # say "last" if we find it
719 }
720 else {
721 $timeout--;
722 }
723 }
724 if ($timeout==0) {
726 die "Waited $STALL_DEFAULT seconds and never saw what I wanted\n";
727 }
728
730 For a serial port to work under Unix, you need the ability to do
731 several types of operations. With POSIX, these operations are
732 implemented with a set of "tc*" functions. However, not all Unix
733 systems follow this correctly. In those cases, the functions change,
734 but the variables used as parameters generally turn out to be the same.
735 Get/Set RTS
737 This is only available through the
738 bit-set(TIOCMBIS)/bit-clear(TIOCMBIC) ioctl function using the RTS
739 value(TIOCM_RTS).
740 ioctl($handle,$on ? $TIOCMBIS : $TIOCMBIC, $TIOCM_RTS);
742 Get/Set DTR
744 This is available through the bit-set(TIOCMBIS)/bit-clear(TIOCMBIC)
745 ioctl function using the DTR value(TIOCM_DTR)
746 ioctl($handle,$on ? $TIOCMBIS : $TIOCMBIC, $TIOCM_DTR);
748 or available through the DTRSET/DTRCLEAR ioctl functions, if they
750 exist.
751 ioctl($handle,$on ? $TIOCSDTR : $TIOCCDTR, 0);
753 Get modem lines
755 To read Clear To Send (CTS), Data Set Ready (DSR), Ring Indicator
756 (RING), and Carrier Detect (CD/RLSD), the TIOCMGET ioctl function
757 must be used.
758 ioctl($handle, $TIOCMGET, $status);
760 To decode the individual modem lines, some bits have multiple
762 possible constants:
763 Clear To Send (CTS)
765 TIOCM_CTS
766 Data Set Ready (DSR)
768 TIOCM_DSR
769 Ring Indicator (RING)
771 TIOCM_RNG TIOCM_RI
772 Carrier Detect (CD/RLSD)
774 TIOCM_CAR TIOCM_CD
775 Get Buffer Status
777 To get information about the state of the serial port input and
778 output buffers, the TIOCINQ and TIOCOUTQ ioctl functions must be
779 used. I'm not totally sure what is returned by these functions
780 across all Unix systems. Under Linux, it is the integer number of
781 characters in the buffer.
782 ioctl($handle,$in ? $TIOCINQ : $TIOCOUTQ, $count);
784 $count = unpack('i',$count);
785 Get Line Status
787 To get information about the state of the serial transmission line
788 (to see if a write has made its way totally out of the serial port
789 buffer), the TIOCSERGETLSR ioctl function must be used.
790 Additionally, the "Get Buffer Status" methods must be functioning,
791 as well as having the first bit of the result set (Linux is
792 TIOCSER_TEMT, others unknown, but we've been using TIOCM_LE even
793 though that should be returned from the TIOCMGET ioctl).
794 ioctl($handle,$TIOCSERGETLSR, $status);
796 $done = (unpack('i', $status) & $TIOCSER_TEMT);
797 Set Flow Control
799 Some Unix systems require special TCGETX/TCSETX ioctls functions
800 and the CTSXON/RTSXOFF constants to turn on and off CTS/RTS "hard"
801 flow control instead of just using the normal POSIX tcsetattr
802 calls.
803 ioctl($handle, $TCGETX, $flags);
805 @bytes = unpack('SSSS',$flags);
806 $bytes[0] = $on ? ($CTSXON | $RTSXOFF) : 0;
807 $flags = pack('SSSS',@bytes);
808 ioctl($handle, $TCSETX, $flags);
809
811 The current version of the module has been tested with Perl 5.003 and
812 above. It was initially ported from Win32 and was designed to be used
813 without requiring a compiler or using XS. Since everything is
814 (sometimes convoluted but still pure) Perl, you can fix flaws and
815 change limits if required. But please file a bug report if you do.
816 The read method, and tied methods which call it, currently can use a
818 fixed timeout which approximates behavior of the Win32::SerialPort
819 read_const_time and read_char_time methods. It is used internally by
820 select. If the timeout is set to zero, the read call will return
821 immediately. A read larger than 255 bytes will be split internally into
822 255-byte POSIX calls due to limitations of select and VMIN. The
823 timeout is reset for each 255-byte segment. Hence, for large reads, use
824 a read_const_time suitable for a 255-byte read. All of this is
825 expeimental in Version 0.055.
826 $PortObj->read_const_time(500); # 500 milliseconds = 0.5 seconds
828 $PortObj->read_char_time(5); # avg time between read char
829 The timing model defines the total time allowed to complete the
831 operation. A fixed overhead time is added to the product of bytes and
832 per_byte_time.
833 Read_Total = read_const_time + (read_char_time * bytes_to_read)
835 Write timeouts and read_interval timeouts are not currently supported.
837 On some machines, reads larger than 4,096 bytes may be truncated at
839 4,096, regardless of the read size or read timing settings used. In
840 this case, try turning on or increasing the inter-character delay on
841 your serial device. Also try setting the read size to
842 $PortObj->read(1) or $PortObj->read(255)
844 and performing multiple reads until the transfer is completed.
846
848 See the limitations about lockfiles. Experiment if you like.
849 With all the currently unimplemented features, we don't need any more.
851 But there probably are some.
852 Please send comments and bug reports to kees@outflux.net.
854
856 Win32::SerialPort Functions Not Currently Supported
857 $LatchErrorFlags = $PortObj->reset_error;
858 $PortObj->read_interval(100); # max time between read char
860 $PortObj->write_char_time(5);
861 $PortObj->write_const_time(100);
862 Functions Handled in a POSIX system by "stty"
864 xon_limit xoff_limit xon_char xoff_char
865 eof_char event_char error_char stty_intr
866 stty_quit stty_eof stty_eol stty_erase
867 stty_kill stty_clear is_stty_clear stty_bsdel
868 stty_echoke stty_echoctl stty_ocrnl stty_onlcr
869 Win32::SerialPort Functions Not Ported to POSIX
871 transmit_char
872 Win32API::CommPort Functions Not Ported to POSIX
874 init_done fetch_DCB update_DCB initialize
875 are_buffers are_baudrate are_handshake are_parity
876 are_databits are_stopbits is_handshake xmit_imm_char
877 is_baudrate is_parity is_databits is_write_char_time
878 debug_comm is_xon_limit is_xoff_limit is_read_const_time
879 suspend_tx is_eof_char is_event_char is_read_char_time
880 is_read_buf is_write_buf is_buffers is_read_interval
881 is_error_char resume_tx is_stopbits is_write_const_time
882 is_binary is_status write_bg is_parity_enable
883 is_modemlines read_bg read_done break_active
884 xoff_active is_read_buf is_write_buf xon_active
885 "raw" Win32 API Calls and Constants
887 A large number of Win32-specific elements have been omitted. Most of
888 these are only available in Win32::SerialPort and Win32API::CommPort as
889 optional Exports. The list includes the following:
890 :RAW
892 The API Wrapper Methods and Constants used only to support them
893 including PURGE_*, SET*, CLR*, EV_*, and ERROR_IO*
894 :COMMPROP
896 The Constants used for Feature and Properties Detection including
897 BAUD_*, PST_*, PCF_*, SP_*, DATABITS_*, STOPBITS_*, PARITY_*, and
898 COMMPROP_INITIALIZED
899 :DCB
901 The constants for the Win32 Device Control Block including CBR_*,
902 DTR_*, RTS_*, *PARITY, *STOPBIT*, and FM_*
903 Compatibility
905 This code implements the functions required to support the MisterHouse
906 Home Automation software by Bruce Winter. It does not attempt to
907 support functions from Win32::SerialPort such as stty_emulation that
908 already have POSIX implementations or to replicate Win32 idosyncracies.
909 However, the supported functions are intended to clone the equivalent
910 functions in Win32::SerialPort and Win32API::CommPort. Any
911 discrepancies or omissions should be considered bugs and reported to
912 the maintainer.
913
915 Based on Win32::SerialPort.pm, Version 0.8, by Bill Birthisel
916 Ported to linux/POSIX by Joe Doss for MisterHouse
917 Ported to Solaris/POSIX by Kees Cook for Sendpage
918 Ported to BSD/POSIX by Kees Cook
919 Ported to Perl XS by Kees Cook
920 Currently maintained by:
922 Kees Cook, kees@outflux.net, http://outflux.net/
923
925 Win32API::CommPort
926 Win32::SerialPort
928 perltoot - Tom Christiansen's Object-Oriented Tutorial
930
932 Copyright (C) 1999, Bill Birthisel. All rights reserved.
933 Copyright (C) 2000-2007, Kees Cook. All rights reserved.
934 This module is free software; you can redistribute it and/or modify it
936 under the same terms as Perl itself.
937
939 Hey! The above document had some coding errors, which are explained
940 below:
941 Around line 2647:
943 You can't have =items (as at line 2653) unless the first thing
944 after the =over is an =item
945 Around line 2737:
947 You can't have =items (as at line 2747) unless the first thing
948 after the =over is an =item
949perl v5.36.0 2023-01-20 SerialPort(3)