README

-----Ruby/SerialPort-----

-- Description --

Ruby/SerialPort is a Ruby library that provides a class for using
RS-232 serial ports.  This class also contains low-level functions to
check and set the current state of the signals on the line.

The native Windows version of this library supports Microsoft's Visual C++
and Borland's C++ compilers.

-- Installation --

This gem is hosted at GitHub. Before you can install this, or any other GitHub gem you must
add it as a gem source:
  gem sources -a http://gems.github.com

Then you can install the gem as normal:
  sudo gem install toholio-serialport

-- Testing --

* test/miniterm.rb

Ruby's copy of miniterm.c !


-- API --

  **** Class SerialPort, Parent IO ****

    ** Class constants **

       VERSION -> aString (this release is "0.6")
       NONE, HARD, SOFT, SPACE, MARK, EVEN, ODD -> anInteger

    ** Class methods **

      * new(port_num [, modem_parameters]) -> aSerialPort
      * open(port_num [, modem_parameters]) -> aSerialPort
      * open(port_num [, modem_parameters]) {|aSerialPort| block} ->
                value of the block

        port_num -> anInteger: port number, 0 for first port which is
                      "/dev/ttyS0" on GNU/Linux and "COM1" on Windows,
                or  aString: file name of the device (example: "/dev/ttyS2")

        Optional modem_parameters:

        baudrate -> anInteger: from 50 to 256000, depends on platform.

        databits -> anInteger: from 5 to 8 (4 is allowed on Windows)

        stopbits -> anInteger: 1 or 2 (1.5 is not supported)

        parity -> anInteger: SerialPort::NONE, SerialPort::EVEN,
                  SerialPort::ODD, SerialPort::MARK, SerialPort::SPACE
                  (MARK and SPACE are not supported on Posix)

        Raise an argError on bad argument.

        SerialPort::new and SerialPort::open without a block return an
        instance of SerialPort.  SerialPort::open with a block passes
        a SerialPort to the block and closes it when the block exits
        (like File::open).


    ** Instance methods **

      * modem_params() -> aHash
      * modem_params=(aHash) -> aHash
      * get_modem_params() -> aHash
      * set_modem_params(aHash) -> aHash
      * set_modem_params(baudrate [, databits [, stopbits [, parity]]])

        Get and set the modem parameters.  Hash keys are "baud", "data_bits",
        "stop_bits", and "parity" (see above).

        Parameters not present in the hash or set to nil remain unchanged.
        Default parameter values for the set_modem_params method are:
        databits = 8, stopbits = 1, parity = (databits == 8 ?
        SerialPort::NONE : SerialPort::EVEN).

      * baud() -> anInteger
      * baud=(anInteger) -> anInteger
      * data_bits() -> 4, 5, 6, 7, or 8
      * data_bits=(anInteger) -> anInteger
      * stop_bits() -> 1 or 2
      * stop_bits=(anInteger) -> anInteger
      * parity() -> anInteger: SerialPort::NONE, SerialPort::EVEN,
          SerialPort::ODD, SerialPort::MARK, or SerialPort::SPACE
      * parity=(anInteger) -> anInteger

        Get and set the corresponding modem parameter.

      * flow_control() -> anInteger
      * flow_control=(anInteger) -> anInteger

        Get and set the flow control: SerialPort::NONE, SerialPort::HARD,
        SerialPort::SOFT, or (SerialPort::HARD | SerialPort::SOFT).

        Note: SerialPort::HARD mode is not supported on all platforms.
        SerialPort::HARD uses RTS/CTS handshaking; DSR/DTR is not
        supported.

      * read_timeout() -> anInteger
      * read_timeout=(anInteger) -> anInteger
      * write_timeout() -> anInteger
      * write_timeout=(anInteger) -> anInteger

        Get and set timeout values (in milliseconds) for reading and writing.
        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.

        Note: Read timeouts don't mix well with multi-threading.

        Note: Under Posix, write timeouts are not implemented.

      * break(time) -> nil

        Send a break for the given time.  

        time -> anInteger: tenths-of-a-second for the break.
        Note: Under Posix, this value is very approximate.

      * signals() -> aHash

        Return a hash with the state of each line status bit.  Keys are
        "rts", "dtr", "cts", "dsr", "dcd", and "ri".

        Note: Under Windows, the rts and dtr values are not included.

      * rts()
      * dtr()
      * cts()
      * dsr()
      * dcd()
      * ri() -> 0 or 1

      * rts=(0 or 1)
      * dtr=(0 or 1) -> 0 or 1

        Get and set the corresponding line status bit.

        Note: Under Windows, rts() and dtr() are not implemented.

-- License --

GPL

Guillaume Pierronnet <moumar@netcourrier.com>
Alan Stern <stern@rowland.harvard.edu>
Tobin Richard <tobin.richard@gmail.com>