README.md

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