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
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
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
@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
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); }
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; }
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); }
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); }
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); }
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; }
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); }
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); }
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); }
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); }
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); }
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 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 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 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; }
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; }
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; }
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
orODD
(Windows allows alsoMARK
andSPACE
)
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); }
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); }
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; }
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); }
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); }
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); }
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); }
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); }
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
orODD
(Windows allows alsoMARK
andSPACE
)
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); }
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; }
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); }
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; }
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); }
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); }