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 <https://github.com/chemeris/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 available [online](http://libmodbus.org/documentation) or
  63 as manual pages after installation.
  64
  65 The documentation is based on
  66 [AsciiDoc](http://www.methods.co.nz/asciidoc/).  Only man pages are built
  67 by default with `make` command, you can run `make htmldoc` in *docs* directory
  68 to generate HTML files.
  69
  70 Testing
  71 -------
  72
  73 Some tests are provided in *tests* directory, you can freely edit the source
  74 code to fit your needs (it's Free Software :).
  75
  76 See *tests/README* for a description of each program.
  77
  78 For a quick test of libmodbus, you can run the following programs in two shells:
  79
  80 1. ./unit-test-server
  81 2. ./unit-test-client
  82
  83 By default, all TCP unit tests will be executed (see --help for options).
  84
  85 It's also possible to run the unit tests with `make check`.
  86
  87 To report a bug or to contribute
  88 --------------------------------
  89
  90 See [CONTRIBUTING](CONTRIBUTING.md) document.