Class: SerialPort

Inherits:
IO
  • Object
show all
Defined in:
lib/serialport.rb,
lib/serialport/version.rb,
ext/native/serialport.c

Overview

This class is used for communication over a serial port. In addition to the methods here, you can use Ruby IO methods, e.g. read, write, getc, readlines, etc.

See Also:

Constant Summary collapse

VERSION = 
"1.4.0"
NONE =

0

INT2FIX(NONE)
HARD =

1

INT2FIX(HARD)
SOFT =

2

INT2FIX(SOFT)
SPACE =

0

INT2FIX(SPACE)
MARK =

1

INT2FIX(MARK)
EVEN =

2

INT2FIX(EVEN)
ODD =

3

INT2FIX(ODD)

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.create(_port) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

See Also:



50
51
52
53
 
# File 'ext/native/serialport.c', line 50

static VALUE sp_create(VALUE class, VALUE _port)
{
   return sp_create_impl(class, _port);
}

.new(port, *params) ⇒ SerialPort .new(port, *params) ⇒ SerialPort

Creates a serial port object. Accepts the port identifier and a variable list for configuration as paramaters or hash. Please see SerialPort#set_modem_params

Overloads:

  • .new(port, *params) ⇒ SerialPort

    Parameters:

    • port (Integer) —

      the serial port number, where 0 is mapped to “COM1” on Windows, “/dev/ttyS0” on Linux, “/dev/cuaa0” on Mac OS X, etc.

  • .new(port, *params) ⇒ SerialPort

    Parameters:

    • port (String) —

      the serial port file e.g. “/dev/ttyS0”

Returns:

See Also:



25
26
27
28
29
30
31
32
33
34
 
# File 'lib/serialport.rb', line 25

def SerialPort::new(port, *params)
   sp = create(port)
   begin
      sp.set_modem_params(*params)
   rescue
      sp.close
      raise
   end
   return sp
end

.open(port, *params) {|serial_port| ... } ⇒ Object

This behaves like SerialPort#new, except that you can pass a block to which the new serial port object will be passed. In this case the connection is automaticaly closed when the block has finished.

Yields:

  • (serial_port) —

    the serial port number or filename

See Also:



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/serialport.rb', line 43

def SerialPort::open(port, *params)
   sp = create(port)
   begin
      sp.set_modem_params(*params)
   rescue
      sp.close
      raise
   end
   if (block_given?)
     begin
        yield sp
     ensure
        sp.close
     end
     return nil
   end
   return sp
end

Instance Method Details

#baud ⇒ Integer

Get the current baud rate

Returns:

  • (Integer) —

    the current baud rate

See Also:



306
307
308
309
310
311
312
313
 
# File 'ext/native/serialport.c', line 306

static VALUE sp_get_data_rate(VALUE self)
{
   struct modem_params mp;

   get_modem_params(self, &mp);

   return INT2FIX(mp.data_rate);
}

#baud=(data_rate) ⇒ Integer

Set the baud rate

Parameters:

  • data_rate (Integer) —

    the baud rate

Returns:

  • (Integer) —

    the original data_rate parameter

See Also:



235
236
237
238
239
240
241
242
243
244
 
# File 'ext/native/serialport.c', line 235

static VALUE sp_set_data_rate(VALUE self, VALUE data_rate)
{
   VALUE argv[4];

   argv[0] = data_rate;
   argv[1] = argv[2] = argv[3] = Qnil;
   sp_set_modem_params(4, argv, self);

   return data_rate;
}

#break(time) ⇒ nil

Note:

(POSIX) this value is very approximate

Send a break for the given time

Parameters:

  • time (Integer) —

    break time in tenths-of-a-second

Returns:

  • (nil) 


94
95
96
97
 
# File 'ext/native/serialport.c', line 94

static VALUE sp_break(VALUE self, VALUE time)
{
   return sp_break_impl(self, time);
}

#cts ⇒ Integer

Get the state of the CTS line

Returns:

  • (Integer) —

    the state of the CTS line, 0 or 1

See Also:



397
398
399
400
401
402
403
404
 
# File 'ext/native/serialport.c', line 397

static VALUE sp_get_cts(VALUE self)
{
   struct line_signals ls;

   get_line_signals_helper(self, &ls);

   return INT2FIX(ls.cts);
}

#data_bits ⇒ Integer

Get the current data bits

Returns:

  • (Integer) —

    the current number of data bits

See Also:



321
322
323
324
325
326
327
328
 
# File 'ext/native/serialport.c', line 321

static VALUE sp_get_data_bits(VALUE self)
{
   struct modem_params mp;

   get_modem_params(self, &mp);

   return INT2FIX(mp.data_bits);
}

#data_bits=(data_bits) ⇒ Integer

Set the data bits

Parameters:

  • data_bits (Integer) —

    the number of data bits

Returns:

  • (Integer) —

    the original data_bits parameter

See Also:



253
254
255
256
257
258
259
260
261
262
 
# File 'ext/native/serialport.c', line 253

static VALUE sp_set_data_bits(VALUE self, VALUE data_bits)
{
   VALUE argv[4];

   argv[1] = data_bits;
   argv[0] = argv[2] = argv[3] = Qnil;
   sp_set_modem_params(4, argv, self);

   return data_bits;
}

#dcd ⇒ Integer

Get the state of the DCD line

Returns:

  • (Integer) —

    the state of the DCD line, 0 or 1

See Also:



427
428
429
430
431
432
433
434
 
# File 'ext/native/serialport.c', line 427

static VALUE sp_get_dcd(VALUE self)
{
   struct line_signals ls;

   get_line_signals_helper(self, &ls);

   return INT2FIX(ls.dcd);
}

#dsr ⇒ Integer

Get the state of the DSR line

Returns:

  • (Integer) —

    the state of the DSR line, 0 or 1

See Also:



412
413
414
415
416
417
418
419
 
# File 'ext/native/serialport.c', line 412

static VALUE sp_get_dsr(VALUE self)
{
   struct line_signals ls;

   get_line_signals_helper(self, &ls);

   return INT2FIX(ls.dsr);
}

#dtr ⇒ Integer

Note:

(Windows) DTR is not available

Get the state of the DTR line

Returns:

  • (Integer) —

    the state of DTR line, 0 or 1



105
106
107
108
 
# File 'ext/native/serialport.c', line 105

static VALUE sp_get_dtr(VALUE self)
{
   return sp_get_dtr_impl(self);
}

#dtr=(val) ⇒ Integer

Set the state of the DTR line

Parameters:

  • val (Integer) —

    the desired state of the DTR line, 0 or 1

Returns:

  • (Integer) —

    the original val parameter



160
161
162
163
 
# File 'ext/native/serialport.c', line 160

static VALUE sp_set_dtr(VALUE self, VALUE val)
{
   return sp_set_dtr_impl(self, val);
}

#flow_control ⇒ Integer

Get the flow control flag

Returns:

  • (Integer) —

    the flow control flag

See Also:

  • #set_flow_control


116
117
118
119
 
# File 'ext/native/serialport.c', line 116

static VALUE sp_get_flow_control(VALUE self)
{
   return sp_get_flow_control_impl(self);
}

#flow_control=(val) ⇒ Integer

Note:

SerialPort::HARD mode is not supported on all platforms.

Note:

SerialPort::HARD uses RTS/CTS handshaking. DSR/DTR is not supported.

Set the flow control

Parameters:

  • val (Integer) —

    the flow control flag, NONE, HARD, SOFT, or (HARD | SOFT)

Returns:

  • (Integer) —

    the original val parameter



175
176
177
178
 
# File 'ext/native/serialport.c', line 175

static VALUE sp_set_flow_control(VALUE self, VALUE val)
{
   return sp_set_flow_control_impl(self, val);
}

#flush_input ⇒ Boolean

Flush data received but not read.

Returns:

  • (Boolean) —

    true on success or false if an error occurs.



486
487
488
489
 
# File 'ext/native/serialport.c', line 486

static VALUE sp_flush_input_data(VALUE self)
{
   return sp_flush_input_data_impl(self);
}

#flush_output ⇒ Boolean

Flush data written but not transmitted.

Returns:

  • (Boolean) —

    true on success or false if an error occurs.



496
497
498
499
 
# File 'ext/native/serialport.c', line 496

static VALUE sp_flush_output_data(VALUE self)
{
   return sp_flush_output_data_impl(self);
}

#get_modem_params ⇒ Hash

Get the configure of the serial port

Returns:

  • (Hash) —

    the serial port configuration

See Also:



366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
 
# File 'ext/native/serialport.c', line 366

static VALUE sp_get_modem_params(VALUE self)
{
   struct modem_params mp;
   VALUE hash;

   get_modem_params(self, &mp);

   hash = rb_hash_new();

   rb_hash_aset(hash, sBaud, INT2FIX(mp.data_rate));
   rb_hash_aset(hash, sDataBits, INT2FIX(mp.data_bits));
   rb_hash_aset(hash, sStopBits, INT2FIX(mp.stop_bits));
   rb_hash_aset(hash, sParity, INT2FIX(mp.parity));

   return hash;
}

#get_signals ⇒ Hash

Note:

(Windows) the rts and dtr values are not included

Note:

This method is implemented as both SerialPort#signals and SerialPort#get_signals

Return a hash with the state of each line status bit. Keys:

"rts", "dtr", "cts", "dsr", "dcd", and "ri".

Returns:

  • (Hash) —

    the state line info



460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
 
# File 'ext/native/serialport.c', line 460

static VALUE sp_signals(VALUE self)
{
   struct line_signals ls;
   VALUE hash;

   get_line_signals_helper(self, &ls);

   hash = rb_hash_new();

#if !(defined(OS_MSWIN) || defined(OS_BCCWIN) || defined(OS_MINGW))
   rb_hash_aset(hash, sRts, INT2FIX(ls.rts));
   rb_hash_aset(hash, sDtr, INT2FIX(ls.dtr));
#endif
   rb_hash_aset(hash, sCts, INT2FIX(ls.cts));
   rb_hash_aset(hash, sDsr, INT2FIX(ls.dsr));
   rb_hash_aset(hash, sDcd, INT2FIX(ls.dcd));
   rb_hash_aset(hash, sRi, INT2FIX(ls.ri));

   return hash;
}

#modem_params ⇒ Hash

Get the configure of the serial port

Returns:

  • (Hash) —

    the serial port configuration

See Also:



366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
 
# File 'ext/native/serialport.c', line 366

static VALUE sp_get_modem_params(VALUE self)
{
   struct modem_params mp;
   VALUE hash;

   get_modem_params(self, &mp);

   hash = rb_hash_new();

   rb_hash_aset(hash, sBaud, INT2FIX(mp.data_rate));
   rb_hash_aset(hash, sDataBits, INT2FIX(mp.data_bits));
   rb_hash_aset(hash, sStopBits, INT2FIX(mp.stop_bits));
   rb_hash_aset(hash, sParity, INT2FIX(mp.parity));

   return hash;
}

#set_modem_params(baud, data_bits, stop_bits, parity) ⇒ Hash #set_modem_params(hash) ⇒ Hash

Configure the serial port. You can pass a hash or multiple values as separate arguments. Invalid or unsupported values will raise an ArgumentError.

When using a hash the following keys are recognized:

“baud”

Integer from 50 to 256000, depending on platform

“data_bits”

Integer from 5 to 8 (4 is allowed on Windows too)

“stop_bits”

Integer, only allowed values are 1 or 2 (1.5 is not supported)

“parity”

One of the constants NONE, EVEN or ODD (Windows allows also MARK and SPACE)

When using separate arguments, they are interpreted as:

(baud, data_bits = 8, stop_bits = 1, parity = (previous_databits == 8 ? NONE : EVEN))

A baudrate of nil will keep the old value. The default parity depends on the number of databits configured before this function call.

Overloads:

  • #set_modem_params(baud, data_bits, stop_bits, parity) ⇒ Hash

    Parameters:

    • baud (Integer) —

      the baud rate

    • data_bits (Integer) —

      the number of data bits

    • stop_bits (Integer) —

      the number of stop bits

    • parity (Integer) —

      the type of parity checking

  • #set_modem_params(hash) ⇒ Hash

    Parameters:

    • opts (Hash) —

      the options to configure port

Returns:

  • (Hash) —

    the original paramters

Raises:

  • (ArgumentError) —

    if values are invalide or unsupported



82
83
84
85
 
# File 'ext/native/serialport.c', line 82

static VALUE sp_set_modem_params(int argc, VALUE *argv, VALUE self)
{
   return sp_set_modem_params_impl(argc, argv, self);
}

#parity ⇒ Integer

Get the current parity

Returns:

  • (Integer) —

    the current parity

See Also:



351
352
353
354
355
356
357
358
 
# File 'ext/native/serialport.c', line 351

static VALUE sp_get_parity(VALUE self)
{
   struct modem_params mp;

   get_modem_params(self, &mp);

   return INT2FIX(mp.parity);
}

#parity=(parity) ⇒ Integer

Set the parity

Parameters:

  • parity (Integer) —

    the parity type

Returns:

  • (Integer) —

    the original parity parameter

See Also:



289
290
291
292
293
294
295
296
297
298
 
# File 'ext/native/serialport.c', line 289

static VALUE sp_set_parity(VALUE self, VALUE parity)
{
   VALUE argv[4];

   argv[3] = parity;
   argv[0] = argv[1] = argv[2] = Qnil;
   sp_set_modem_params(4, argv, self);

   return parity;
}

#read_timeout ⇒ Integer

Get the read timeout value

Returns:

  • (Integer) —

    the read timeout, in milliseconds

See Also:

  • #set_read_timeout


127
128
129
130
 
# File 'ext/native/serialport.c', line 127

static VALUE sp_get_read_timeout(VALUE self)
{
   return sp_get_read_timeout_impl(self);
}

#read_timeout=(val) ⇒ Integer

Note:

Read timeouts don’t mix well with multi-threading

Set the timeout value (in milliseconds) for reading. A negative read timeout will return all the available data without waiting, a zero read timeout will not return until at least one byte is available, and a positive read timeout returns when the requested number of bytes is available or the interval between the arrival of two bytes exceeds the timeout value.

Parameters:

  • timeout (Integer) —

    the read timeout in milliseconds

Returns:

  • (Integer) —

    the original timeout parameter



192
193
194
195
 
# File 'ext/native/serialport.c', line 192

static VALUE sp_set_read_timeout(VALUE self, VALUE val)
{
   return sp_set_read_timeout_impl(self, val);
}

#ri ⇒ Integer

Get the state of the RI line

Returns:

  • (Integer) —

    the state of the RI line, 0 or 1

See Also:



442
443
444
445
446
447
448
449
 
# File 'ext/native/serialport.c', line 442

static VALUE sp_get_ri(VALUE self)
{
   struct line_signals ls;

   get_line_signals_helper(self, &ls);

   return INT2FIX(ls.ri);
}

#rts ⇒ Integer

Note:

(Windows) RTS is not available

Get the state of the RTS line

Returns:

  • (Integer) —

    the state of RTS line, 0 or 1



138
139
140
141
 
# File 'ext/native/serialport.c', line 138

static VALUE sp_get_rts(VALUE self)
{
   return sp_get_rts_impl(self);
}

#rts=(val) ⇒ Integer

Set the state of the RTS line

Parameters:

  • val (Integer) —

    the state of RTS line, 0 or 1

Returns:

  • (Integer) —

    the original val parameter



203
204
205
206
 
# File 'ext/native/serialport.c', line 203

static VALUE sp_set_rts(VALUE self, VALUE val)
{
   return sp_set_rts_impl(self, val);
}

#set_modem_params(baud, data_bits, stop_bits, parity) ⇒ Hash #set_modem_params(hash) ⇒ Hash

Configure the serial port. You can pass a hash or multiple values as separate arguments. Invalid or unsupported values will raise an ArgumentError.

When using a hash the following keys are recognized:

“baud”

Integer from 50 to 256000, depending on platform

“data_bits”

Integer from 5 to 8 (4 is allowed on Windows too)

“stop_bits”

Integer, only allowed values are 1 or 2 (1.5 is not supported)

“parity”

One of the constants NONE, EVEN or ODD (Windows allows also MARK and SPACE)

When using separate arguments, they are interpreted as:

(baud, data_bits = 8, stop_bits = 1, parity = (previous_databits == 8 ? NONE : EVEN))

A baudrate of nil will keep the old value. The default parity depends on the number of databits configured before this function call.

Overloads:

  • #set_modem_params(baud, data_bits, stop_bits, parity) ⇒ Hash

    Parameters:

    • baud (Integer) —

      the baud rate

    • data_bits (Integer) —

      the number of data bits

    • stop_bits (Integer) —

      the number of stop bits

    • parity (Integer) —

      the type of parity checking

  • #set_modem_params(hash) ⇒ Hash

    Parameters:

    • opts (Hash) —

      the options to configure port

Returns:

  • (Hash) —

    the original paramters

Raises:

  • (ArgumentError) —

    if values are invalide or unsupported



82
83
84
85
 
# File 'ext/native/serialport.c', line 82

static VALUE sp_set_modem_params(int argc, VALUE *argv, VALUE self)
{
   return sp_set_modem_params_impl(argc, argv, self);
}

#signals ⇒ Hash

Note:

(Windows) the rts and dtr values are not included

Note:

This method is implemented as both SerialPort#signals and SerialPort#get_signals

Return a hash with the state of each line status bit. Keys:

"rts", "dtr", "cts", "dsr", "dcd", and "ri".

Returns:

  • (Hash) —

    the state line info



460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
 
# File 'ext/native/serialport.c', line 460

static VALUE sp_signals(VALUE self)
{
   struct line_signals ls;
   VALUE hash;

   get_line_signals_helper(self, &ls);

   hash = rb_hash_new();

#if !(defined(OS_MSWIN) || defined(OS_BCCWIN) || defined(OS_MINGW))
   rb_hash_aset(hash, sRts, INT2FIX(ls.rts));
   rb_hash_aset(hash, sDtr, INT2FIX(ls.dtr));
#endif
   rb_hash_aset(hash, sCts, INT2FIX(ls.cts));
   rb_hash_aset(hash, sDsr, INT2FIX(ls.dsr));
   rb_hash_aset(hash, sDcd, INT2FIX(ls.dcd));
   rb_hash_aset(hash, sRi, INT2FIX(ls.ri));

   return hash;
}

#stop_bits ⇒ Integer

Get the current stop bits

Returns:

  • (Integer) —

    the current number of stop bits

See Also:



336
337
338
339
340
341
342
343
 
# File 'ext/native/serialport.c', line 336

static VALUE sp_get_stop_bits(VALUE self)
{
   struct modem_params mp;

   get_modem_params(self, &mp);

   return INT2FIX(mp.stop_bits);
}

#stop_bits=(stop_bits) ⇒ Integer

Set the stop bits

Parameters:

  • stop_bits (Integer) —

    the number of stop bits

Returns:

  • (Integer) —

    the original stop_bits parameter

See Also:



271
272
273
274
275
276
277
278
279
280
 
# File 'ext/native/serialport.c', line 271

static VALUE sp_set_stop_bits(VALUE self, VALUE stop_bits)
{
   VALUE argv[4];

   argv[2] = stop_bits;
   argv[0] = argv[1] = argv[3] = Qnil;
   sp_set_modem_params(4, argv, self);

   return stop_bits;
}

#write_timeout ⇒ Integer

Note:

(POSIX) write timeouts are not implemented

Get the write timeout

Returns:

  • (Integer) —

    the write timeout, in milliseconds



149
150
151
152
 
# File 'ext/native/serialport.c', line 149

static VALUE sp_get_write_timeout(VALUE self)
{
   return sp_get_write_timeout_impl(self);
}

#write_timeout=(val) ⇒ Integer

Note:

(POSIX) write timeouts are not implemented

Set a write timeout

Parameters:

  • val (Integer) —

    the write timeout in milliseconds

Returns:

  • (Integer) —

    the original val parameter



215
216
217
218
 
# File 'ext/native/serialport.c', line 215

static VALUE sp_set_write_timeout(VALUE self, VALUE val)
{
   return sp_set_write_timeout_impl(self, val);
}