gen_serial: generic serial port driver for Erlang
-------------------------------------------------


See doc/gen_serial.html for API documentation.


gen_serial is a generic serial port driver to allow Erlang applications
to use the host's RS-232 serial ports through a single cross platform
API.

Each serial port is managed in its own host OS process, ensuring that
the stability of the Erlang node is not compromised by the gen_serial
driver. The port driver processes cost about 1 MB of memory on Windows
(each), a relatively high price to pay for stablity.


Currently this driver and API has been tested on Windows XP, Windows 7
and Linux. It should also work on Windows 95/98/ME, Windows NT 4,
2000, 2003, and any POSIX compatible (UNIX-like) system. The code also
compiles (but is not tested by this author in any way) on Mac OS X as
well as QNX.


Since the gen_serial module locates the serial_esock(.exe) binary through
its priv directory, it is necessary to put the path of the gen_serial
directory into the code server.  This can be done on the command line
with -pa:

	erl -pa /path/to/gen_serial-0.2/ebin

Alternatively, installing the gen_serial-0.2 directory under the lib/
directory of your Erlang installation (eg. C:\Erlang\lib\ on Windows,
/opt/erlang/lib/erlang/lib/ on Linux) to reside among all other
installed applications will allow Erlang to find it automatically.


A simple test module is also provided as gen_serial_test. This has some
test cases which can be run in one Erlang node (using a loopback serial
cable with a null modem installed and two serial ports on the host) or
between two networked Erlang nodes (using a serial cable with a null
modem to connect the two hosts).


Building gen_serial on UNIX platforms is pretty simple:

	./make.sh

This will call erl -make with the Emakefile and then invoke the Makefile
in c_src/posix to compile the POSIX driver backend.

As an alternative, you may use rebar3 to compile gen_serial as an OTP
application (assuming you already have rebar3 set up):

        rebar3 compile


On Windows, the toplevel make.bat may be used to compile the Erlang
code. The location of your Erlang installation needs to be edited in
the batch file if it is not C:\Erlang.

The backend (native code) is under c_src and can be compiled on the
respective target platform (see README in c_src). A pre-built binary
for Windows is shipped, but it must be compiled before use on UNIX.


The latest version is always available from:
http://github.com/tomszilagyi/gen_serial

Feedback, patches, pull requests welcome.

Have fun!

		Tom Szilagyi
		[email protected]