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 [www.modbus.org](http://www.modbus.org).
  15
  16 The license of libmodbus is *LGPL v2.1 or later*.
  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 The official website is [www.libmodbus.org](http://www.libmodbus.org).
  25
  26 The library is written in C and designed to run on Linux, Mac OS X, FreeBSD, Embox,
  27 QNX and Windows.
  28
  29 You can use the library on MCUs with Embox RTOS.
  30
  31 Installation
  32 ------------
  33
  34 You will only need to install automake, autoconf, libtool and a C compiler (gcc
  35 or clang) to compile the library and asciidoc and xmlto to generate the
  36 documentation (optional).
  37
  38 To install, just run the usual dance, `./configure && make install`. Run
  39 `./autogen.sh` first to generate the `configure` script if required.
  40
  41 You can change installation directory with prefix option, eg. `./configure
  42 --prefix=/usr/local/`. You have to check that the installation library path is
  43 properly set up on your system (*/etc/ld.so.conf.d*) and library cache is up to
  44 date (run `ldconfig` as root if required).
  45
  46 The library provides a *libmodbus.pc* file to use with `pkg-config` to ease your
  47 program compilation and linking.
  48
  49 If you want to compile with Microsoft Visual Studio, you need to install
  50 <https://github.com/chemeris/msinttypes> to fill the absence of stdint.h.
  51
  52 To compile under Windows, install [MinGW](http://www.mingw.org/) and MSYS then
  53 select the common packages (gcc, automake, libtool, etc). The directory
  54 *./src/win32/* contains a Visual C project.
  55
  56 To compile under OS X with [homebrew](http://mxcl.github.com/homebrew/), you
  57 will need to install the following dependencies first: `brew install autoconf
  58 automake libtool`.
  59
  60 To build under Embox, you have to use its build system.
  61
  62 Documentation
  63 -------------
  64
  65 The documentation is available [online](http://libmodbus.org/documentation) or
  66 as manual pages after installation.
  67
  68 The documentation is based on
  69 [AsciiDoc](http://www.methods.co.nz/asciidoc/).  Only man pages are built
  70 by default with `make` command, you can run `make htmldoc` in *doc* directory
  71 to generate HTML files.
  72
  73 Testing
  74 -------
  75
  76 Some tests are provided in *tests* directory, you can freely edit the source
  77 code to fit your needs (it's Free Software :).
  78
  79 See *tests/README* for a description of each program.
  80
  81 For a quick test of libmodbus, you can run the following programs in two shells:
  82
  83 1. ./unit-test-server
  84 2. ./unit-test-client
  85
  86 By default, all TCP unit tests will be executed (see --help for options).
  87
  88 It's also possible to run the unit tests with `make check`.
  89
  90 To report a bug or to contribute
  91 --------------------------------
  92
  93 See [CONTRIBUTING](CONTRIBUTING.md) document.