class SerialPort

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 rubydoc.info/stdlib/core/IO Ruby IO class @see www.cmrr.umn.edu/~strupp/serial.html “Serial Programming Guide for POSIX Operating Systems”

Constants

EVEN

2

HARD

1

MARK

1

NONE

0

ODD

3

SOFT

2

SPACE

0

VERSION

Public Class Methods

new(port, *params) click to toggle source

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

@overload new(port, *params)

@param 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.

@overload new(port, *params)

@param port [String] the serial port file e.g. "/dev/ttyS0"

@return [SerialPort] @see SerialPort#set_modem_params

# 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) { |sp| ... } click to toggle source

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.

@yield [serial_port] the serial port number or filename @see SerialPort#new @see SerialPort#set_modem_params

# 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

Private Class Methods

create(p1) click to toggle source

@api private

@see SerialPort#new @see SerialPort#open

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

Public Instance Methods

baud() click to toggle source

Get the current baud rate

@return [Integer] the current baud rate @see SerialPort#set_modem_params

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

   get_modem_params(self, &mp);

   return INT2FIX(mp.data_rate);
}
baud=(p1) click to toggle source

Set the baud rate

@param data_rate [Integer] the baud rate @return [Integer] the original data_rate parameter @see SerialPort#set_modem_params

static VALUE sp_set_data_rate(self, data_rate)
   VALUE self, 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(p1) click to toggle source

Send a break for the given time

@param time [Integer] break time in tenths-of-a-second @return [nil] @note (POSIX) this value is very approximate

static VALUE sp_break(self, time)
   VALUE self, time;
{
   return sp_break_impl(self, time);
}
cts() click to toggle source

Get the state of the CTS line

@return [Integer] the state of the CTS line, 0 or 1 @see SerialPort#get_signals

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

   get_line_signals_helper(self, &ls);

   return INT2FIX(ls.cts);
}
data_bits() click to toggle source

Get the current data bits

@return [Integer] the current number of data bits @see SerialPort#set_modem_params

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

   get_modem_params(self, &mp);

   return INT2FIX(mp.data_bits);
}
data_bits=(p1) click to toggle source

Set the data bits

@param data_bits [Integer] the number of data bits @return [Integer] the original data_bits parameter @see SerialPort#set_modem_params

static VALUE sp_set_data_bits(self, data_bits)
   VALUE self, 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() click to toggle source

Get the state of the DCD line

@return [Integer] the state of the DCD line, 0 or 1 @see SerialPort#get_signals

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

   get_line_signals_helper(self, &ls);

   return INT2FIX(ls.dcd);
}
dsr() click to toggle source

Get the state of the DSR line

@return [Integer] the state of the DSR line, 0 or 1 @see SerialPort#get_signals

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

   get_line_signals_helper(self, &ls);

   return INT2FIX(ls.dsr);
}
dtr() click to toggle source

Get the state of the DTR line

@note (Windows) DTR is not available @return [Integer] the state of DTR line, 0 or 1

static VALUE sp_get_dtr(self)
   VALUE self;
{
   return sp_get_dtr_impl(self);
}
dtr=(p1) click to toggle source

Set the state of the DTR line

@param val [Integer] the desired state of the DTR line, 0 or 1 @return [Integer] the original val parameter

static VALUE sp_set_dtr(self, val)
   VALUE self, val;
{
   return sp_set_dtr_impl(self, val);
}
flow_control() click to toggle source

Get the flow control flag

@return [Integer] the flow control flag @see SerialPort#set_flow_control

static VALUE sp_get_flow_control(self)
   VALUE self;
{
   return sp_get_flow_control_impl(self);
}
flow_control=(p1) click to toggle source

Set the flow control

@param val [Integer] the flow control flag,

+NONE+, +HARD+, +SOFT+, or (+HARD+ | +SOFT+)

@return [Integer] the original val parameter @note SerialPort::HARD mode is not supported on all platforms. @note SerialPort::HARD uses RTS/CTS handshaking.

DSR/DTR is not supported.
static VALUE sp_set_flow_control(self, val)
   VALUE self, val;
{
   return sp_set_flow_control_impl(self, val);
}
flush_input() click to toggle source

Flush data received but not read.

@return [Boolean] true on success or false if an error occurs.

static VALUE sp_flush_input_data(self)
   VALUE self;
{
   return sp_flush_input_data_impl(self);
}
flush_output() click to toggle source

Flush data written but not transmitted.

@return [Boolean] true on success or false if an error occurs.

static VALUE sp_flush_output_data(self)
   VALUE self;
{
   return sp_flush_output_data_impl(self);
}
get_modem_params() click to toggle source

Get the configure of the serial port

@return [Hash] the serial port configuration @see SerialPort#set_modem_params

static VALUE sp_get_modem_params(self)
   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() click to toggle source

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

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

@return [Hash] the state line info @note (Windows) the rts and dtr values are not included @note This method is implemented as both SerialPort#signals and SerialPort#get_signals

static VALUE sp_signals(self)
   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() click to toggle source

Get the configure of the serial port

@return [Hash] the serial port configuration @see SerialPort#set_modem_params

static VALUE sp_get_modem_params(self)
   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;
}
modem_params=(*args) click to toggle source

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.

@overload set_modem_params(baud, data_bits, stop_bits, parity)

@param baud [Integer] the baud rate
@param data_bits [Integer] the number of data bits
@param stop_bits [Integer] the number of stop bits
@param parity [Integer] the type of parity checking

@overload set_modem_params(hash)

@param opts [Hash] the options to configure port

@return [Hash] the original paramters @raise [ArgumentError] if values are invalide or unsupported

static VALUE sp_set_modem_params(argc, argv, self)
   int argc;
   VALUE *argv, self;
{
   return sp_set_modem_params_impl(argc, argv, self);
}
parity() click to toggle source

Get the current parity

@return [Integer] the current parity @see SerialPort#set_modem_params

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

   get_modem_params(self, &mp);

   return INT2FIX(mp.parity);
}
parity=(p1) click to toggle source

Set the parity

@param parity [Integer] the parity type @return [Integer] the original parity parameter @see SerialPort#set_modem_params

static VALUE sp_set_parity(self, parity)
   VALUE self, 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() click to toggle source

Get the read timeout value

@return [Integer] the read timeout, in milliseconds @see SerialPort#set_read_timeout

static VALUE sp_get_read_timeout(self)
   VALUE self;
{
   return sp_get_read_timeout_impl(self);
}
read_timeout=(p1) click to toggle source

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.

@param timeout [Integer] the read timeout in milliseconds @return [Integer] the original timeout parameter @note Read timeouts don't mix well with multi-threading

static VALUE sp_set_read_timeout(self, val)
   VALUE self, val;
{
   return sp_set_read_timeout_impl(self, val);
}
ri() click to toggle source

Get the state of the RI line

@return [Integer] the state of the RI line, 0 or 1 @see SerialPort#get_signals

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

   get_line_signals_helper(self, &ls);

   return INT2FIX(ls.ri);
}
rts() click to toggle source

Get the state of the RTS line

@return [Integer] the state of RTS line, 0 or 1 @note (Windows) RTS is not available

static VALUE sp_get_rts(self)
   VALUE self;
{
   return sp_get_rts_impl(self);
}
rts=(p1) click to toggle source

Set the state of the RTS line

@param val [Integer] the state of RTS line, 0 or 1 @return [Integer] the original val parameter

static VALUE sp_set_rts(self, val)
   VALUE self, val;
{
   return sp_set_rts_impl(self, val);
}
set_modem_params(*args) click to toggle source

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.

@overload set_modem_params(baud, data_bits, stop_bits, parity)

@param baud [Integer] the baud rate
@param data_bits [Integer] the number of data bits
@param stop_bits [Integer] the number of stop bits
@param parity [Integer] the type of parity checking

@overload set_modem_params(hash)

@param opts [Hash] the options to configure port

@return [Hash] the original paramters @raise [ArgumentError] if values are invalide or unsupported

static VALUE sp_set_modem_params(argc, argv, self)
   int argc;
   VALUE *argv, self;
{
   return sp_set_modem_params_impl(argc, argv, self);
}
signals() click to toggle source

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

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

@return [Hash] the state line info @note (Windows) the rts and dtr values are not included @note This method is implemented as both SerialPort#signals and SerialPort#get_signals

static VALUE sp_signals(self)
   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() click to toggle source

Get the current stop bits

@return [Integer] the current number of stop bits @see SerialPort#set_modem_params for details

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

   get_modem_params(self, &mp);

   return INT2FIX(mp.stop_bits);
}
stop_bits=(p1) click to toggle source

Set the stop bits

@param stop_bits [Integer] the number of stop bits @return [Integer] the original stop_bits parameter @see SerialPort#set_modem_params

static VALUE sp_set_stop_bits(self, stop_bits)
   VALUE self, 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() click to toggle source

Get the write timeout

@return [Integer] the write timeout, in milliseconds @note (POSIX) write timeouts are not implemented

static VALUE sp_get_write_timeout(self)
   VALUE self;
{
   return sp_get_write_timeout_impl(self);
}
write_timeout=(p1) click to toggle source

Set a write timeout

@param val [Integer] the write timeout in milliseconds @return [Integer] the original val parameter @note (POSIX) write timeouts are not implemented

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