README.md

   1 A groovy modbus library
   2 =======================
   3
   4 [![Build Status](https://travis-ci.org/stephane/libmodbus.svg?branch=master)](https://travis-ci.org/stephane/libmodbus)
   5
   6 Overview
   7 --------
   8
   9 libmodbus is a free software library to send/receive data with a device which
  10 respects the Modbus protocol. This library can use a serial port or an Ethernet
  11 connection.
  12
  13 The functions included in the library have been derived from the Modicon Modbus
  14 Protocol Reference Guide which can be obtained from Schneider at
  15 [www.schneiderautomation.com](http://www.schneiderautomation.com).
  16
  17 The license of libmodbus is *LGPL v2.1 or later*.
  18
  19 The documentation is available as manual pages (`man libmodbus` to read general
  20 description and list of available functions) or Web pages
  21 [www.libmodbus.org/documentation/](http://libmodbus.org/documentation/). The
  22 documentation is licensed under the Creative Commons Attribution-ShareAlike
  23 License 3.0 (Unported) (<http://creativecommons.org/licenses/by-sa/3.0/>).
  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
  56 will need to install the following dependencies first: `brew install autoconf
  57 automake libtool`.
  58
  59 Documentation
  60 -------------
  61
  62 The documentation is based on
  63 [AsciiDoc](http://http://www.methods.co.nz/asciidoc/).  Only man pages are built
  64 by default with `make` command, you can run `make htmldoc` in *docs* directory
  65 to generate HTML files.
  66
  67 The documentation is also available [online](http://libmodbus.org/documentation).
  68
  69 Testing
  70 -------
  71
  72 Some tests are provided in *tests* directory, you can freely edit the source
  73 code to fit your needs (it's Free Software :).
  74
  75 See *tests/README* for a description of each program.
  76
  77 For a quick test of libmodbus, you can run the following programs in two shells:
  78
  79 1. ./unit-test-server
  80 2. ./unit-test-client
  81
  82 By default, all TCP unit tests will be executed (see --help for options).
  83
  84 It's also possible to run the unit tests with `make check`.
  85
  86 Report a Bug
  87 ------------
  88
  89 Before reporting a bug, take care to read the documentation (RTFM!) and to
  90 provide enough information:
  91
  92 1. libmodbus version
  93 2. OS/environment/architecture
  94 3. libmodbus backend (TCP, RTU, IPv6)
  95 3. Modbus messages when running in debug mode (`man modbus_set_debug`)
  96
  97 To report your problem, you can:
  98
  99 * fill a bug report on the issue tracker <http://github.com/stephane/libmodbus/issues>.
 100 * or send an email to the libmodbus mailing list [libmodbus@googlegroups.com](https://groups.google.com/forum/#!forum/libmodbus).
 101
 102 If your prefer live talk when your're looking for help or to offer contribution,
 103 there is also a channel called #libmodbus on Freenode.