README.md

   1 # A groovy modbus library
   2
   3 ![Build Status](https://github.com/stephane/libmodbus/actions/workflows/build.yml/badge.svg)
   4
   5 ## Overview
   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 [www.modbus.org](http://www.modbus.org).
  13
  14 The license of libmodbus is *LGPL v2.1 or later*.
  15
  16 The official website is [www.libmodbus.org](http://www.libmodbus.org). The
  17 website contains the latest version of the documentation.
  18
  19 The library is written in C and designed to run on Linux, Mac OS X, FreeBSD, Embox,
  20 QNX and Windows.
  21
  22 You can use the library on MCUs with Embox RTOS.
  23
  24 ## Installation
  25
  26 You will only need to install automake, autoconf, libtool and a C compiler (gcc
  27 or clang) to compile the library and asciidoc and xmlto to generate the
  28 documentation (optional).
  29
  30 To install, just run the usual dance, `./configure && make install`. Run
  31 `./autogen.sh` first to generate the `configure` script if required.
  32
  33 You can change installation directory with prefix option, eg. `./configure
  34 --prefix=/usr/local/`. You have to check that the installation library path is
  35 properly set up on your system (*/etc/ld.so.conf.d*) and library cache is up to
  36 date (run `ldconfig` as root if required).
  37
  38 The library provides a *libmodbus.pc* file to use with `pkg-config` to ease your
  39 program compilation and linking.
  40
  41 If you want to compile with Microsoft Visual Studio, you should follow the
  42 instructions in `./src/win32/README.md`.
  43
  44 To compile under Windows, install [MinGW](http://www.mingw.org/) and MSYS then
  45 select the common packages (gcc, automake, libtool, etc). The directory
  46 *./src/win32/* contains a Visual C project.
  47
  48 To compile under OS X with [homebrew](http://mxcl.github.com/homebrew/), you
  49 will need to install the following dependencies first: `brew install autoconf
  50 automake libtool`.
  51
  52 To build under Embox, you have to use its build system.
  53
  54 ## Testing
  55
  56 Some tests are provided in *tests* directory, you can freely edit the source
  57 code to fit your needs (it's Free Software :).
  58
  59 See *tests/README* for a description of each program.
  60
  61 For a quick test of libmodbus, you can run the following programs in two shells:
  62
  63 1. ./unit-test-server
  64 2. ./unit-test-client
  65
  66 By default, all TCP unit tests will be executed (see --help for options).
  67
  68 It's also possible to run the unit tests with `make check`.
  69
  70 ## To report a bug or to contribute
  71
  72 See [CONTRIBUTING](CONTRIBUTING.md) document.
  73
  74 ## Documentation
  75
  76 You can serve the local documentation with:
  77
  78 ```shell
  79 pip install mkdocs-material
  80 mkdocs serve
  81 ```