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.3.2"
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 ⇒ 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:



29
30
 
# File 'ext/native/serialport.c', line 29

static VALUE sp_create(class, _port)
VALUE 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:



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

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:



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

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:



305
306
 
# File 'ext/native/serialport.c', line 305

static VALUE sp_get_data_rate(self)
VALUE self;

#baud= ⇒ Integer

Set the baud rate

Parameters:

  • data_rate (Integer) —

    the baud rate

Returns:

  • (Integer) —

    the original data_rate parameter

See Also:



230
231
 
# File 'ext/native/serialport.c', line 230

static VALUE sp_set_data_rate(self, data_rate)
VALUE self, data_rate;

#break ⇒ 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) 


76
77
 
# File 'ext/native/serialport.c', line 76

static VALUE sp_break(self, time)
VALUE self, time;

#cts ⇒ Integer

Get the state of the CTS line

Returns:

  • (Integer) —

    the state of the CTS line, 0 or 1

See Also:



403
404
 
# File 'ext/native/serialport.c', line 403

static VALUE sp_get_cts(self)
VALUE self;

#data_bits ⇒ Integer

Get the current data bits

Returns:

  • (Integer) —

    the current number of data bits

See Also:



321
322
 
# File 'ext/native/serialport.c', line 321

static VALUE sp_get_data_bits(self)
VALUE self;

#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:



249
250
 
# File 'ext/native/serialport.c', line 249

static VALUE sp_set_data_bits(self, data_bits)
VALUE self, data_bits;

#dcd ⇒ Integer

Get the state of the DCD line

Returns:

  • (Integer) —

    the state of the DCD line, 0 or 1

See Also:



435
436
 
# File 'ext/native/serialport.c', line 435

static VALUE sp_get_dcd(self)
VALUE self;

#dsr ⇒ Integer

Get the state of the DSR line

Returns:

  • (Integer) —

    the state of the DSR line, 0 or 1

See Also:



419
420
 
# File 'ext/native/serialport.c', line 419

static VALUE sp_get_dsr(self)
VALUE self;

#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



88
89
 
# File 'ext/native/serialport.c', line 88

static VALUE sp_get_dtr(self)
VALUE self;

#dtr= ⇒ 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



148
149
 
# File 'ext/native/serialport.c', line 148

static VALUE sp_set_dtr(self, val)
VALUE self, val;

#flow_control ⇒ Integer

Get the flow control flag

Returns:

  • (Integer) —

    the flow control flag

See Also:

  • #set_flow_control


100
101
 
# File 'ext/native/serialport.c', line 100

static VALUE sp_get_flow_control(self)
VALUE self;

#flow_control= ⇒ 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



164
165
 
# File 'ext/native/serialport.c', line 164

static VALUE sp_set_flow_control(self, val)
VALUE self, val;

#flush_input ⇒ Boolean

Flush data received but not read.

Returns:

  • (Boolean) —

    true on success or false if an error occurs.



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

static VALUE sp_flush_input_data(self)
VALUE self;

#flush_output ⇒ Boolean

Flush data written but not transmitted.

Returns:

  • (Boolean) —

    true on success or false if an error occurs.



508
509
 
# File 'ext/native/serialport.c', line 508

static VALUE sp_flush_output_data(self)
VALUE self;

#get_modem_params ⇒ Hash

Get the configure of the serial port

Returns:

  • (Hash) —

    the serial port configuration

See Also:



369
370
 
# File 'ext/native/serialport.c', line 369

static VALUE sp_get_modem_params(self)
VALUE self;

#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



470
471
 
# File 'ext/native/serialport.c', line 470

static VALUE sp_signals(self)
VALUE self;

#modem_params ⇒ Hash

Get the configure of the serial port

Returns:

  • (Hash) —

    the serial port configuration

See Also:



369
370
 
# File 'ext/native/serialport.c', line 369

static VALUE sp_get_modem_params(self)
VALUE self;

#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



62
63
 
# File 'ext/native/serialport.c', line 62

static VALUE sp_set_modem_params(argc, argv, self)
int argc;

#parity ⇒ Integer

Get the current parity

Returns:

  • (Integer) —

    the current parity

See Also:



353
354
 
# File 'ext/native/serialport.c', line 353

static VALUE sp_get_parity(self)
VALUE self;

#parity= ⇒ Integer

Set the parity

Parameters:

  • parity (Integer) —

    the parity type

Returns:

  • (Integer) —

    the original parity parameter

See Also:



287
288
 
# File 'ext/native/serialport.c', line 287

static VALUE sp_set_parity(self, parity)
VALUE self, parity;

#read_timeout ⇒ Integer

Get the read timeout value

Returns:

  • (Integer) —

    the read timeout, in milliseconds

See Also:

  • #set_read_timeout


112
113
 
# File 'ext/native/serialport.c', line 112

static VALUE sp_get_read_timeout(self)
VALUE self;

#read_timeout= ⇒ 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



182
183
 
# File 'ext/native/serialport.c', line 182

static VALUE sp_set_read_timeout(self, val)
VALUE self, val;

#ri ⇒ Integer

Get the state of the RI line

Returns:

  • (Integer) —

    the state of the RI line, 0 or 1

See Also:



451
452
 
# File 'ext/native/serialport.c', line 451

static VALUE sp_get_ri(self)
VALUE self;

#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



124
125
 
# File 'ext/native/serialport.c', line 124

static VALUE sp_get_rts(self)
VALUE self;

#rts= ⇒ 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



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

static VALUE sp_set_rts(self, val)
VALUE 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



62
63
 
# File 'ext/native/serialport.c', line 62

static VALUE sp_set_modem_params(argc, argv, self)
int argc;

#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



470
471
 
# File 'ext/native/serialport.c', line 470

static VALUE sp_signals(self)
VALUE self;

#stop_bits ⇒ Integer

Get the current stop bits

Returns:

  • (Integer) —

    the current number of stop bits

See Also:



337
338
 
# File 'ext/native/serialport.c', line 337

static VALUE sp_get_stop_bits(self)
VALUE self;

#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:



268
269
 
# File 'ext/native/serialport.c', line 268

static VALUE sp_set_stop_bits(self, stop_bits)
VALUE self, stop_bits;

#write_timeout ⇒ Integer

Note:

(POSIX) write timeouts are not implemented

Get the write timeout

Returns:

  • (Integer) —

    the write timeout, in milliseconds



136
137
 
# File 'ext/native/serialport.c', line 136

static VALUE sp_get_write_timeout(self)
VALUE self;

#write_timeout= ⇒ 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



207
208
 
# File 'ext/native/serialport.c', line 207

static VALUE sp_set_write_timeout(self, val)
VALUE self, val;