README.md

   1 A groovy modbus library
   2 =======================
   3
   4 Overview
   5 --------
   6
   7 libmodbus is a free software library to send/receive data with a device which
   8 respects the Modbus protocol. This library can use a serial port or an Ethernet
   9 connection.
  10
  11 The functions included in the library have been derived from the Modicon Modbus
  12 Protocol Reference Guide which can be obtained from Schneider at
  13 [www.schneiderautomation.com](http://www.schneiderautomation.com).
  14
  15 The license of libmodbus is *LGPL v2.1 or later* and the licence of programs in
  16 tests directory is GPL v3.
  17
  18 The documentation is available as manual pages (`man libmodbus` to read general
  19 description and list of available functions) or Web pages
  20 [www.libmodbus.org/documentation/](http://libmodbus.org/documentation/). The
  21 documentation is licensed under the Creative Commons Attribution-ShareAlike
  22 License 3.0 (Unported) (<http://creativecommons.org/licenses/by-sa/3.0/>).
  23
  24
  25 The official website is [www.libmodbus.org](http://www.libmodbus.org).
  26
  27 The library is written in C and designed to run on Linux, Mac OS X, FreeBSD and
  28 QNX and Windows.
  29
  30 Installation
  31 ------------
  32
  33 You will only need to install automake, autoconf, libtool and a C compiler (gcc
  34 or clang) to compile the library and asciidoc and xmlto to generate the
  35 documentation (optional).
  36
  37 To install, just run the usual dance, `./configure && make install`. Run
  38 `./autogen.sh` first to generate the `configure` script if required.
  39
  40 You can change installation directory with prefix option, eg. `./configure
  41 --prefix=/usr/local/`. You have to check that the installation library path is
  42 properly set up on your system (`/etc/ld.so.conf.d`) and library cache is up to
  43 date (run `ldconfig` as root if required).
  44
  45 The library provides a `libmodbus.pc` file to use with `pkg-config` to ease your
  46 program compilation and linking.
  47
  48 If you want to compile with Microsoft Visual Studio, you need to install
  49 <http://code.google.com/p/msinttypes/> to fill the absence of stdint.h.
  50
  51 To compile under Windows, install [MinGW](http://www.mingw.org/) and MSYS then
  52 select the common packages (gcc, automake, libtool, etc). The directory
  53 `./src/win32/` contains a Visual C project.
  54
  55 To compile under OS X with [homebrew](http://mxcl.github.com/homebrew/), you will need
  56 to install the following dependencies first: `brew install autoconf automake libtool`.
  57
  58 Testing
  59 -------
  60
  61 Some tests are provided in *tests* directory, you can freely edit the source
  62 code to fit your needs (it's Free Software :).
  63
  64 See *tests/README* for a description of each program.
  65
  66 For a quick test of libmodbus, you can run the following programs in two shells:
  67
  68 1. ./unit-test-server
  69 2. ./unit-test-client
  70
  71 By default, all TCP unit tests will be executed (see --help for options).
  72
  73 Report a Bug
  74 ------------
  75
  76 Before reporting a bug, take care to read the documentation (RTFM!) and to
  77 provide enough information:
  78
  79 1. libmodbus version
  80 2. OS/environment/architecture
  81 3. libmodbus backend (TCP, RTU, IPv6)
  82 3. Modbus messages when running in debug mode (`man modbus_set_debug`)
  83
  84 To report your problem, you can:
  85
  86 * fill a bug report on the issue tracker <http://github.com/stephane/libmodbus/issues>.
  87 * or send an email to the libmodbus mailing list [libmodbus@googlegroups.com](https://groups.google.com/forum/#!forum/libmodbus).
  88
  89 If your prefer live talk when your're looking for help or to offer contribution,
  90 there is also a channel called #libmodbus on Freenode.