Peter M. Groen / libmodbus

Commit 6254ede9156095ee0300076bf92c930066ce542f

Authored by Stéphane Raimbault
1 parent acd36e62

Add documentation based on AsciiDoc tools 

Each function is decribed in one txt file. The file libmodbus.txt
offers an overview of the library.

It's possible to generate HTML and man outputs from the txt file.
The documentation can be generated only if you have the required
tools (asciidoc and xmlto).

Better results are obtained with AsciiDoc v8.6+
Inline Side-by-side
Showing 31 changed files with 1512 additions and 1 deletions
Makefile.am
  View file @6254ede
1 1 EXTRA_DIST = MIGRATION README.rst libmodbus.spec
2   -SUBDIRS = src tests
  2 +SUBDIRS = src doc tests
3 3  
4 4 pkgconfigdir = $(libdir)/pkgconfig
5 5 pkgconfig_DATA = libmodbus.pc
... ...
acinclude.m4 0 → 100644
  View file @6254ede
  1 +dnl ##############################################################################
  2 +dnl # AC_LIBMODBUS_CHECK_DOC_BUILD #
  3 +dnl # Check whether to build documentation and install man-pages #
  4 +dnl ##############################################################################
  5 +AC_DEFUN([AC_LIBMODBUS_CHECK_DOC_BUILD], [{
  6 + # Allow user to disable doc build
  7 + AC_ARG_WITH([documentation], [AS_HELP_STRING([--without-documentation],
  8 + [disable documentation build even if asciidoc and xmlto are present [default=no]])])
  9 +
  10 + if test "x$with_documentation" = "xno"; then
  11 + ac_libmodbus_build_doc="no"
  12 + ac_libmodbus_install_man="no"
  13 + else
  14 + # Determine whether or not documentation should be built and installed.
  15 + ac_libmodbus_build_doc="yes"
  16 + ac_libmodbus_install_man="yes"
  17 + # Check for asciidoc and xmlto and don't build the docs if these are not installed.
  18 + AC_CHECK_PROG(ac_libmodbus_have_asciidoc, asciidoc, yes, no)
  19 + AC_CHECK_PROG(ac_libmodbus_have_xmlto, xmlto, yes, no)
  20 + if test "x$ac_libmodbus_have_asciidoc" = "xno" -o "x$ac_libmodbus_have_xmlto" = "xno"; then
  21 + ac_libmodbus_build_doc="no"
  22 + # Tarballs built with 'make dist' ship with prebuilt documentation.
  23 + if ! test -f doc/modbus.7; then
  24 + ac_libmodbus_install_man="no"
  25 + AC_MSG_WARN([You are building an unreleased version of libmodbus and asciidoc or xmlto are not installed.])
  26 + AC_MSG_WARN([Documentation will not be built and manual pages will not be installed.])
  27 + fi
  28 + fi
  29 +
  30 + # Do not install man pages if on mingw
  31 + if test "x$ac_libmodbus_on_mingw32" = "xyes"; then
  32 + ac_libmodbus_install_man="no"
  33 + fi
  34 + fi
  35 +
  36 + AC_MSG_CHECKING([whether to build documentation])
  37 + AC_MSG_RESULT([$ac_libmodbus_build_doc])
  38 +
  39 + AC_MSG_CHECKING([whether to install manpages])
  40 + AC_MSG_RESULT([$ac_libmodbus_install_man])
  41 +
  42 + AM_CONDITIONAL(BUILD_DOC, test "x$ac_libmodbus_build_doc" = "xyes")
  43 + AM_CONDITIONAL(INSTALL_MAN, test "x$ac_libmodbus_install_man" = "xyes")
  44 +}])
... ...
configure.ac
  View file @6254ede
... ... @@ -79,6 +79,9 @@ AC_CHECK_HEADERS([ \
79 79 netdb.h \
80 80 ])
81 81  
  82 +# Check whether to build docs / install man pages
  83 +AC_LIBMODBUS_CHECK_DOC_BUILD
  84 +
82 85 # Checks for header files.
83 86 AC_HEADER_STDC
84 87  
... ... @@ -125,6 +128,7 @@ AC_CONFIG_FILES([
125 128 Makefile
126 129 src/Makefile
127 130 src/modbus-version.h
  131 + doc/Makefile
128 132 tests/Makefile
129 133 libmodbus.pc
130 134 ])
... ...
doc/Makefile.am 0 → 100644
  View file @6254ede
  1 +MAN3 = \
  2 + modbus_close.3 \
  3 + modbus_connect.3 \
  4 + modbus_flush.3 \
  5 + modbus_free.3 \
  6 + modbus_get_header_length.3 \
  7 + modbus_get_timeout_begin.3 \
  8 + modbus_get_timeout_end.3 \
  9 + modbus_new_rtu.3 \
  10 + modbus_new_tcp_pi.3 \
  11 + modbus_new_tcp.3 \
  12 + modbus_read_bits.3 \
  13 + modbus_read_input_bits.3 \
  14 + modbus_read_input_registers.3 \
  15 + modbus_read_registers.3 \
  16 + modbus_set_debug.3 \
  17 + modbus_set_error_recovery.3 \
  18 + modbus_set_slave.3 \
  19 + modbus_set_timeout_begin.3 \
  20 + modbus_set_timeout_end.3 \
  21 + modbus_strerror.3 \
  22 + modbus_write_bits.3 \
  23 + modbus_write_bit.3 \
  24 + modbus_write_registers.3 \
  25 + modbus_write_register.3
  26 +MAN7 = libmodbus.7
  27 +
  28 +MAN_DOC = $(MAN3) $(MAN7)
  29 +
  30 +MAN_TXT = $(MAN3:%.3=%.txt)
  31 +MAN_TXT += $(MAN7:%.7=%.txt)
  32 +MAN_HTML = $(MAN_TXT:%.txt=%.html)
  33 +
  34 +if INSTALL_MAN
  35 +dist_man_MANS = $(MAN_DOC)
  36 +doc : $(MAN_DOC)
  37 +endif
  38 +
  39 +EXTRA_DIST = asciidoc.conf $(MAN_TXT)
  40 +if BUILD_DOC
  41 +EXTRA_DIST += $(MAN_HTML)
  42 +html : $(MAN_HTML)
  43 +endif
  44 +
  45 +MAINTAINERCLEANFILES = $(MAN_DOC) $(MAN_HTML)
  46 +
  47 +dist-hook : $(MAN_DOC) $(MAN_HTML)
  48 +
  49 +html: $(MAN_HTML)
  50 +
  51 +if BUILD_DOC
  52 +SUFFIXES=.html .txt .xml .1 .3 .7
  53 +
  54 +.txt.html:
  55 + asciidoc -d manpage -b xhtml11 -f asciidoc.conf \
  56 + -alibmodbus_version=@LIBMODBUS_VERSION@ $<
  57 +.txt.xml:
  58 + asciidoc -d manpage -b docbook -f asciidoc.conf \
  59 + -alibmodbus_version=@LIBMODBUS_VERSION@ $<
  60 +.xml.1:
  61 + xmlto man $<
  62 +.xml.3:
  63 + xmlto man $<
  64 +.xml.7:
  65 + xmlto man $<
  66 +
  67 +clean:
  68 + rm -f *.1 *.3 *.7
  69 + rm -f *.html
  70 +
  71 +endif
... ...
doc/asciidoc.conf 0 → 100644
  View file @6254ede
  1 +[paradef-default]
  2 +literal-style=template="literalparagraph"
  3 +
  4 +[macros]
  5 +(?su)[\\]?(?P<name>linkmb):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
  6 +
  7 +ifdef::backend-docbook[]
  8 +[linkmb-inlinemacro]
  9 +{0%{target}}
  10 +{0#<citerefentry>}
  11 +{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
  12 +{0#</citerefentry>}
  13 +endif::backend-docbook[]
  14 +
  15 +ifdef::backend-xhtml11[]
  16 +[linkmb-inlinemacro]
  17 +<a href="{target}.html">{target}{0?({0})}</a>
  18 +endif::backend-xhtml11[]
  19 +
  20 +ifdef::doctype-manpage[]
  21 +ifdef::backend-docbook[]
  22 +[header]
  23 +template::[header-declarations]
  24 +<refentry>
  25 +<refmeta>
  26 +<refentrytitle>{mantitle}</refentrytitle>
  27 +<manvolnum>{manvolnum}</manvolnum>
  28 +<refmiscinfo class="source">libmodbus</refmiscinfo>
  29 +<refmiscinfo class="version">{libmodbus_version}</refmiscinfo>
  30 +<refmiscinfo class="manual">Libmodbus Manual</refmiscinfo>
  31 +</refmeta>
  32 +<refnamediv>
  33 + <refname>{manname}</refname>
  34 + <refpurpose>{manpurpose}</refpurpose>
  35 +</refnamediv>
  36 +endif::backend-docbook[]
  37 +endif::doctype-manpage[]
  38 +
  39 +ifdef::backend-xhtml11[]
  40 +[footer]
  41 +</div>
  42 +{disable-javascript%<div id="footnotes"><hr /></div>}
  43 +<div id="footer">
  44 +<div id="footer-text">
  45 +libmodbus {libmodbus_version}<br />
  46 +Last updated {docdate} {doctime}
  47 +</div>
  48 +</div>
  49 +</body>
  50 +</html>
  51 +endif::backend-xhtml11[]
... ...
doc/libmodbus.txt 0 → 100644
  View file @6254ede
  1 +libmodbus(7)
  2 +============
  3 +
  4 +
  5 +NAME
  6 +----
  7 +libmodbus - fast and portable Modbus library
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*#include <modbus.h>*
  13 +
  14 +*cc* \`pkg-config --cflags --libs libmodbus` 'files'
  15 +
  16 +
  17 +DESCRIPTION
  18 +-----------
  19 +libmodbus is a library to send/receive data with a device which respects the
  20 +Modbus protocol. This library contains various backends to communicate over
  21 +different networks (eg. serial in RTU mode or Ethernet in TCP/IPv6). The
  22 +http://www.modbus.org site provides documentation about the protocol at
  23 +http://www.modbus.org/specs.php.
  24 +
  25 +libmodbus provides an abstraction of the lower communication layers and offers
  26 +the same API on all supported platforms.
  27 +
  28 +This documentation presents an overview of libmodbus concepts, describes how
  29 +libmodbus abstracts Modbus communication with different hardware and platforms
  30 +and provides a reference manual for the functions provided by the libmodbus
  31 +library.
  32 +
  33 +
  34 +Contexts
  35 +~~~~~~~~
  36 +The Modbus protocol contains many variants (eg. serial RTU or Ehternet TCP), to
  37 +ease the implementation of a variant, the library was designed to use a backend
  38 +for each variant. The backends are also a convenient way to fulfill other
  39 +requirements (eg. real-time operations). Each backend offers a specific function
  40 +to create a new 'modbus_t' context. The 'modbus_t' context is an opaque
  41 +structure containing all necessary information to etablish a connection with
  42 +others Modbus devices according to the selected variant.
  43 +
  44 +You can choose the best context for your needs among:
  45 +
  46 +RTU Context
  47 +^^^^^^^^^^^
  48 +The RTU backend (Remote Terminal Unit) is used in serial communication and makes
  49 +use of a compact, binary representation of the data for protocol
  50 +communication. The RTU format follows the commands/data with a cyclic redundancy
  51 +check checksum as an error check mechanism to ensure the reliability of
  52 +data. Modbus RTU is the most common implementation available for Modbus. A
  53 +Modbus RTU message must be transmitted continuously without inter-character
  54 +hesitations (extract from Wikipedia, Modbus, http://en.wikipedia.org/wiki/Modbus
  55 +(as of Mar. 13, 2011, 20:51 GMT).
  56 +
  57 +Many Modbus devices can be connected together on the same physical link so you
  58 +need to define which slave is concerned by the message with
  59 +linkmb:modbus_set_slave[3]. If you're running a slave (server) the slave number
  60 +is used to filter messages.
  61 +
  62 +Create a Modbus RTU context::
  63 + linkmb:modbus_new_rtu[3]
  64 +
  65 +TCP (IPv4) Context
  66 +^^^^^^^^^^^^^^^^^^
  67 +The TCP backend implements a Modbus variant used for communications over
  68 +TCP/IPv4 networks. It does not require a checksum calculation as lower layer
  69 +takes care of the same.
  70 +
  71 +Create a Modbus TCP context::
  72 + linkmb:modbus_new_tcp[3]
  73 +
  74 +
  75 +TCP PI (IPv4 and IPv6) Context
  76 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  77 +The TCP PI (Protocol Indepedent) backend implements a Modbus variant used for
  78 +communications over TCP IPv4 and IPv6 networks. It does not require a checksum
  79 +calculation as lower layer takes care of the same.
  80 +
  81 +Contrary to the TCP IPv4 only backend, the TCP PI backend offers hostname
  82 +resolution but it consumes about 1Kb of additional memory.
  83 +
  84 +Create a Modbus TCP context::
  85 + linkmb:modbus_new_tcp_pi[3]
  86 +
  87 +
  88 +Common
  89 +^^^^^^
  90 +Before using any libmodbus functions, the caller must allocate and initialize a
  91 +'modbus_t' context with functions explained above, then the following functions
  92 +are provided to modify and free a 'context':
  93 +
  94 +Free libmodbus context::
  95 + linkmb:modbus_free[3]
  96 +
  97 +Context setters and getters::
  98 + linkmb:modbus_set_debug[3]
  99 + linkmb:modbus_set_error_recovery[3]
  100 + linkmb:modbus_set_slave[3]
  101 + linkmb:modbus_get_timeout_begin[3]
  102 + linkmb:modbus_set_timeout_begin[3]
  103 + linkmb:modbus_get_timeout_end[3]
  104 + linkmb:modbus_set_timeout_end[3]
  105 + linkmb:modbus_get_header_length[3]
  106 +
  107 +A libmodbus 'context' is thread safe and may be shared among as many application
  108 +threads as necessary, without any additional locking required on the part of the
  109 +caller.
  110 +
  111 +
  112 +Connection
  113 +~~~~~~~~~~
  114 +The following functions are provided to establish and close a connection with
  115 +Modbus devices:
  116 +
  117 +Establish a connection::
  118 + linkmb:modbus_connect[3]
  119 +
  120 +Close a connection::
  121 + linkmb:modbus_close[3]
  122 +
  123 +Flush a connection::
  124 + linkmb:modbus_flush[3]
  125 +
  126 +
  127 +Data
  128 +~~~~
  129 +The Modbus protocol defines different data types and functions to read and write
  130 +them from/to remote devices.
  131 +
  132 +Read data::
  133 + linkmb:modbus_read_bits[3]
  134 + linkmb:modbus_read_input_bits[3]
  135 + linkmb:modbus_read_registers[3]
  136 + linkmb:modbus_read_input_registers[3]
  137 +
  138 +Write data::
  139 + linkmb:modbus_write_bit[3]
  140 + linkmb:modbus_write_register[3]
  141 + linkmb:modbus_write_bits[3]
  142 + linkmb:modbus_write_registers[3]
  143 +
  144 +
  145 +ERROR HANDLING
  146 +--------------
  147 +The libmodbus functions handle errors using the standard conventions found on
  148 +POSIX systems. Generally, this means that upon failure a libmodbus function
  149 +shall return either a NULL value (if returning a pointer) or a negative value
  150 +(if returning an integer), and the actual error code shall be stored in the
  151 +'errno' variable.
  152 +
  153 +The _modbus_strerror()_ function is provided to translate libmodbus-specific
  154 +error codes into error message strings; for details refer to
  155 +linkmb:modbus_strerror[3].
  156 +
  157 +
  158 +MISCELLANEOUS
  159 +-------------
  160 +The _LIBMODBUS_VERSION_STRING_ constant indicates the libmodbus version the
  161 +program has been compiled against. The variables 'libmodbus_version_major',
  162 +'libmodbus_version_minor', 'libmodbus_version_micro' give the version the
  163 +program is linked against.
  164 +
  165 +
  166 +AUTHORS
  167 +-------
  168 +The libmodbus documentation was written by Stéphane Raimbault
  169 +<stephane.raimbault@gmail.com>
  170 +
  171 +
  172 +RESOURCES
  173 +---------
  174 +Main web site: <http://www.libmodbus.org/>
  175 +
  176 +Report bugs on the issue tracker at
  177 +<http://github.com/stephane/libmodbus/issues>.
  178 +
  179 +
  180 +COPYING
  181 +-------
  182 +Free use of this software is granted under the terms of the GNU Lesser General
  183 +Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER`
  184 +included with the libmodbus distribution.
... ...
doc/modbus_close.txt 0 → 100644
  View file @6254ede
  1 +modbus_close(3)
  2 +===============
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_close - close a Modbus connection
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_close(*modbus_t 'ctx');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_close()_ function shall close the connection established with the
  18 +backend set in the context.
  19 +
  20 +
  21 +RETURN VALUE
  22 +------------
  23 +The _modbus_close()_ function shall return 0 if successful. Otherwise it shall
  24 +return -1 and set errno.
  25 +
  26 +
  27 +EXAMPLE
  28 +-------
  29 +[source,c]
  30 +-------------------
  31 +modbus_t *ctx;
  32 +
  33 +ctx = modbus_new_tcp("127.0.0.1", 502);
  34 +if (modbus_connect(ctx) == -1) {
  35 + fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
  36 + modbus_free(ctx);
  37 + return -1;
  38 +}
  39 +
  40 +modbus_close(ctx);
  41 +modbus_free(ctx);
  42 +-------------------
  43 +
  44 +SEE ALSO
  45 +--------
  46 +linkmb:modbus_connect[3]
  47 +
  48 +
  49 +AUTHORS
  50 +-------
  51 +The libmodbus documentation was written by Stéphane Raimbault
  52 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_connect.txt 0 → 100644
  View file @6254ede
  1 +modbus_connect(3)
  2 +=================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_connect - establish a Modbus connection
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_connect(*modbus_t 'ctx');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_connect()_ function shall etablish a connection to a Modbus server,
  18 +a network or a bus using the context information of libmodbus context given in
  19 +argument.
  20 +
  21 +
  22 +RETURN VALUE
  23 +------------
  24 +The modbus_connect() function shall return 0 if successful. Otherwise it shall
  25 +return -1 and set errno to one of the values defined by the system calls of the
  26 +underlying platform.
  27 +
  28 +
  29 +EXAMPLE
  30 +-------
  31 +[source,c]
  32 +-------------------
  33 +modbus_t *ctx;
  34 +
  35 +ctx = modbus_new_tcp("127.0.0.1", 502);
  36 +if (modbus_connect(ctx) == -1) {
  37 + fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
  38 + modbus_free(ctx);
  39 + return -1;
  40 +}
  41 +-------------------
  42 +
  43 +
  44 +SEE ALSO
  45 +--------
  46 +linkmb:modbus_close[3]
  47 +
  48 +
  49 +AUTHORS
  50 +-------
  51 +The libmodbus documentation was written by Stéphane Raimbault
  52 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_flush.txt 0 → 100644
  View file @6254ede
  1 +modbus_flush(3)
  2 +===============
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_flush - flush non-transmitted data
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_flush(*modbus_t 'ctx');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_flush()_ function shall discard data received but not read to the
  18 +socket or file descriptor associated to the context 'ctx'.
  19 +
  20 +
  21 +RETURN VALUE
  22 +------------
  23 +The _modbus_flush()_ function shall return 0 or the number of flushed bytes if
  24 +successful. Otherwise it shall return -1 and set errno.
  25 +
  26 +
  27 +AUTHORS
  28 +-------
  29 +The libmodbus documentation was written by Stéphane Raimbault
  30 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_free.txt 0 → 100644
  View file @6254ede
  1 +modbus_free(3)
  2 +==============
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_free - free a libmodbus context
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*void modbus_free(*modbus_t 'ctx');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_free()_ function shall free an allocated modbus_t structure.
  18 +
  19 +
  20 +RETURN VALUE
  21 +------------
  22 +There is no return values.
  23 +
  24 +
  25 +SEE ALSO
  26 +--------
  27 +linkmb:libmodbus[3]
  28 +
  29 +
  30 +AUTHORS
  31 +-------
  32 +The libmodbus documentation was written by Stéphane Raimbault
  33 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_get_header_length.txt 0 → 100644
  View file @6254ede
  1 +modbus_get_header_length(3)
  2 +===========================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_get_header_length - retrieve the current header length
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_get_header_length(*modbus_t 'ctx');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_get_header_length()_ function shall retrieve the current header
  18 +length from the backend. This fonction is convenient to manipulate a message and
  19 +so its limited to low-level operations.
  20 +
  21 +
  22 +RETURN VALUE
  23 +------------
  24 +The header length as integer value.
  25 +
  26 +
  27 +SEE ALSO
  28 +--------
  29 +linkmb:libmodbus[7]
  30 +
  31 +
  32 +AUTHORS
  33 +-------
  34 +The libmodbus documentation was written by Stéphane Raimbault
  35 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_get_timeout_begin.txt 0 → 100644
  View file @6254ede
  1 +modbus_get_timeout_begin(3)
  2 +===========================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_get_timeout_begin - get timeout of begin of message
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*void modbus_get_timeout_begin(*modbus_t 'ctx', struct timeval *'timeout');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_get_timeout_begin()_ function shall store the current timeout of
  18 +begin of message in the 'timeout' argument.
  19 +
  20 +
  21 +RETURN VALUE
  22 +------------
  23 +There is no return values.
  24 +
  25 +
  26 +EXAMPLE
  27 +-------
  28 +[source,c]
  29 +-------------------
  30 +struct timeval timeout_begin_old;
  31 +struct timeval timeout_begin_new;
  32 +
  33 +/* Save original timeout */
  34 +modbus_get_timeout_begin(ctx, &timeout_begin_old);
  35 +
  36 +/* Define a new and too short timeout! */
  37 +timeout_begin_new.tv_sec = 0;
  38 +timeout_begin_new.tv_usec = 0;
  39 +modbus_set_timeout_begin(ctx, &timeout_begin_new);
  40 +-------------------
  41 +
  42 +
  43 +SEE ALSO
  44 +--------
  45 +linkmb:modbus_set_timeout_begin[3]
  46 +linkmb:modbus_get_timeout_end[3]
  47 +linkmb:modbus_set_timeout_end[3]
  48 +
  49 +
  50 +AUTHORS
  51 +-------
  52 +The libmodbus documentation was written by Stéphane Raimbault
  53 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_get_timeout_end.txt 0 → 100644
  View file @6254ede
  1 +modbus_get_timeout_end(3)
  2 +===========================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_get_timeout_end - get timeout of end of message
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*void modbus_get_timeout_end(*modbus_t 'ctx', struct timeval *'timeout');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_get_timeout_end()_ function shall store the current timeout between
  18 +the begin and the end of message in the 'timeout' argument.
  19 +
  20 +
  21 +RETURN VALUE
  22 +------------
  23 +There is no return values.
  24 +
  25 +
  26 +EXAMPLE
  27 +-------
  28 +[source,c]
  29 +-------------------
  30 +struct timeval timeout_end;
  31 +
  32 +/* Save original timeout */
  33 +modbus_get_timeout_end(ctx, &timeout_end);
  34 +-------------------
  35 +
  36 +
  37 +SEE ALSO
  38 +--------
  39 +linkmb:modbus_get_timeout_begin[3]
  40 +linkmb:modbus_set_timeout_begin[3]
  41 +linkmb:modbus_set_timeout_end[3]
  42 +
  43 +
  44 +AUTHORS
  45 +-------
  46 +The libmodbus documentation was written by Stéphane Raimbault
  47 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_new_rtu.txt 0 → 100644
  View file @6254ede
  1 +modbus_new_rtu(3)
  2 +=================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_new_rtu - create a libmodbus context for RTU
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*modbus_t modbus_new_rtu(const char *'device', int 'baud',
  13 + char 'parity', int 'data_bit', int 'stop_bit')*
  14 +
  15 +
  16 +
  17 +DESCRIPTION
  18 +-----------
  19 +
  20 +The _modbus_new_rtu()_ function shall allocate and initialize a modbus_t
  21 +structure to communicate in RTU mode on a serial line.
  22 +
  23 +The _device_ argument specifies the name of the serial port handled by the OS,
  24 +eg. '/dev/ttyS0' or '/dev/ttyUSB0'. On Windons, it's necessary to prepend COM
  25 +name with '\\.\' for COM number greater than 9, eg. '\\\\.\\COM10'. See
  26 +http://msdn.microsoft.com/en-us/library/aa365247(v=vs.85).aspx for details
  27 +
  28 +The _baud_ argument specifies the baud rate of the communication, eg. 9600,
  29 +19200, 57600, 115200, etc.
  30 +
  31 +The _parity_ argument can have one of the following values:::
  32 +* _N_ for none
  33 +* _E_ for even
  34 +* _O_ for odd
  35 +
  36 +The _data_bits_ argument specifies the number of bits of data, the allowed
  37 +values are 5, 6, 7 and 8.
  38 +
  39 +The _stop_bits_ argument specifies the bits of stop, the allowed values are 1
  40 +and 2.
  41 +
  42 +
  43 +RETURN VALUE
  44 +------------
  45 +The _modbus_new_rtu()_ function shall return a pointer to a *modbus_t* structure
  46 +if successful. Otherwise it shall return NULL and set errno to one of the values
  47 +defined below.
  48 +
  49 +
  50 +ERRORS
  51 +------
  52 +*EINVAL*::
  53 +An invalid argument was given.
  54 +
  55 +
  56 +EXAMPLE
  57 +-------
  58 +[source,c]
  59 +-------------------
  60 +modbus_t *ctx;
  61 +
  62 +ctx = modbus_new_ru("/dev/ttyUSB0", 115200, 'N', 8, 1);
  63 +if (ctx == NULL) {
  64 + fprintf(stderr, "Unable to create the libmodbus context\n");
  65 + return -1;
  66 +}
  67 +-------------------
  68 +
  69 +SEE ALSO
  70 +--------
  71 +linkmb:modbus_new_tcp[3]
  72 +linkmb:modbus_free[3]
  73 +
  74 +
  75 +AUTHORS
  76 +-------
  77 +The libmodbus documentation was written by Stéphane Raimbault
  78 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_new_tcp.txt 0 → 100644
  View file @6254ede
  1 +modbus_new_tcp(3)
  2 +=================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_new_tcp - create a libmodbus context for TCP/IPv4
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*modbus_t modbus_new_tcp(const char *'ip', int 'port');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_new_tcp()_ function shall allocate and initialize a modbus_t
  18 +structure to communicate with a Modbus TCP/IPv4 server.
  19 +
  20 +The _ip_ argument specifies the IP address of the server to which the client
  21 +wants etablish a connection.
  22 +
  23 +The _port_ argument is the TCP port to use. Set the port to
  24 +_MODBUS_TCP_DEFAULT_PORT_ to use the default one (502). It’s convenient to use a
  25 +port number greater than or equal to 1024 because it’s not necessary to have
  26 +administrator privileges.
  27 +
  28 +
  29 +RETURN VALUE
  30 +------------
  31 +The _modbus_new_tcp()_ function shall return a pointer to a *modbus_t* structure
  32 +if successful. Otherwise it shall return NULL and set errno to one of the values
  33 +defined below.
  34 +
  35 +
  36 +ERRORS
  37 +------
  38 +*EINVAL*::
  39 +An invalid IP address was given.
  40 +
  41 +
  42 +EXAMPLE
  43 +-------
  44 +[source,c]
  45 +-------------------
  46 +modbus_t *ctx;
  47 +
  48 +ctx = modbus_new_tcp("127.0.0.1", 1502);
  49 +if (ctx == NULL) {
  50 + fprintf(stderr, "Unable to allocate libmodbus context\n");
  51 + return -1;
  52 +}
  53 +
  54 +if (modbus_connect(ctx) == -1) {
  55 + fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
  56 + modbus_free(ctx);
  57 + return -1;
  58 +}
  59 +-------------------
  60 +
  61 +SEE ALSO
  62 +--------
  63 +linkmb:modbus_new_rtu[3]
  64 +linkmb:modbus_free[3]
  65 +
  66 +
  67 +AUTHORS
  68 +-------
  69 +The libmodbus documentation was written by Stéphane Raimbault
  70 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_new_tcp_pi.txt 0 → 100644
  View file @6254ede
  1 +modbus_new_tcp_pi(3)
  2 +====================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_new_tcp_pi - create a libmodbus context for TCP Protocol Independent
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*modbus_t modbus_new_tcp_pi(const char *'node', const char *'service');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_new_tcp_pi()_ function shall allocate and initialize a modbus_t
  18 +structure to communicate with a Modbus TCP IPv4 or Ipv6 server.
  19 +
  20 +The _node_ argument specifies the host name or IP address of the host to connect
  21 +to, eg. '192.168.0.5' , '::1' or 'server.com'.
  22 +
  23 +The _service_ argument is the service name/port number to connect to. To use the
  24 +default Modbus port use the string "502". On many Unix systems, it’s
  25 +convenient to use a port number greater than or equal to 1024 because it’s not
  26 +necessary to have administrator privileges.
  27 +
  28 +
  29 +RETURN VALUE
  30 +------------
  31 +The _modbus_new_tcp_pi()_ function shall return a pointer to a *modbus_t* structure
  32 +if successful. Otherwise it shall return NULL and set errno to one of the values
  33 +defined below.
  34 +
  35 +
  36 +ERRORS
  37 +------
  38 +*EINVAL*::
  39 +The node string is empty or has been truncated. The service string is empty or
  40 +has been truncated.
  41 +
  42 +
  43 +EXAMPLE
  44 +-------
  45 +[source,c]
  46 +-------------------
  47 +modbus_t *ctx;
  48 +
  49 +ctx = modbus_new_tcp_pi("::1", "1502");
  50 +if (ctx == NULL) {
  51 + fprintf(stderr, "Unable to allocate libmodbus context\n");
  52 + return -1;
  53 +}
  54 +
  55 +if (modbus_connect(ctx) == -1) {
  56 + fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
  57 + modbus_free(ctx);
  58 + return -1;
  59 +}
  60 +-------------------
  61 +
  62 +SEE ALSO
  63 +--------
  64 +linkmb:modbus_new_tcp[3]
  65 +linkmb:modbus_new_rtu[3]
  66 +linkmb:modbus_free[3]
  67 +
  68 +
  69 +AUTHORS
  70 +-------
  71 +The libmodbus documentation was written by Stéphane Raimbault
  72 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_read_bits.txt 0 → 100644
  View file @6254ede
  1 +modbus_read_bits(3)
  2 +===================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_read_bits - read many bits
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_read_bits(modbus_t *'ctx', int 'addr', int 'nb', uint8_t *'dest')*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_read_bits()_ function shall read the status of the 'nb' bits (coils)
  18 +to the address 'addr' of the remote device. The result of reading is stored in
  19 +'dest' array as unsigned bytes (8 bits) set to _TRUE_ or _FALSE_.
  20 +
  21 +You must take care to allocate enough memory to store the results in 'dest'
  22 +(at least 'nb' * sizeof(uint8_t)).
  23 +
  24 +The function uses the Modbus function code 0x01 (read coil status).
  25 +
  26 +
  27 +RETURN VALUE
  28 +------------
  29 +The _modbus_read_bits()_ function shall return the number of read bits if
  30 +successful. Otherwise it shall return -1 and set errno.
  31 +
  32 +
  33 +ERRORS
  34 +------
  35 +EMBMDATA::
  36 +Too many bits requested
  37 +
  38 +
  39 +SEE ALSO
  40 +--------
  41 +linkmb:modbus_write_bit[3]
  42 +linkmb:modbus_write_bits[3]
  43 +
  44 +
  45 +AUTHORS
  46 +-------
  47 +The libmodbus documentation was written by Stéphane Raimbault
  48 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_read_input_bits.txt 0 → 100644
  View file @6254ede
  1 +modbus_read_input_bits(3)
  2 +=========================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_read_input_bits - read many input bits
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_read_input_bits(modbus_t *'ctx', int 'addr', int 'nb', uint8_t *'dest');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_read_input_bits()_ function shall read the content of the 'nb' input
  18 +bits to the address 'addr' of the remote device. The result of reading is stored
  19 +in 'dest' array as unsigned bytes (8 bits) set to _TRUE_ or _FALSE_.
  20 +
  21 +You must take care to allocate enough memory to store the results in 'dest'
  22 +(at least 'nb' * sizeof(uint8_t)).
  23 +
  24 +The function uses the Modbus function code 0x03 (read input status).
  25 +
  26 +
  27 +RETURN VALUE
  28 +------------
  29 +The _modbus_read_input_status()_ function shall return the number of read
  30 +input status if successful. Otherwise it shall return -1 and set errno.
  31 +
  32 +
  33 +ERRORS
  34 +------
  35 +EMBMDATA::
  36 +Too many discrete inputs requested
  37 +
  38 +
  39 +SEE ALSO
  40 +--------
  41 +linkmb:modbus_write_input_bits[3]
  42 +
  43 +
  44 +AUTHORS
  45 +-------
  46 +The libmodbus documentation was written by Stéphane Raimbault
  47 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_read_input_registers.txt 0 → 100644
  View file @6254ede
  1 +modbus_read_input_registers(3)
  2 +==============================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_read_input_registers - read many input registers
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_read_input_registers(modbus_t *'ctx', int 'addr', int 'nb', uint16_t *'dest')*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_read_input_registers()_ function shall read the content of the 'nb'
  18 +input registers to address 'addr' of the remote device. The result of the
  19 +reading is stored in 'dest' array as word values (16 bits).
  20 +
  21 +You must take care to allocate enough memory to store the results in 'dest' (at
  22 +least 'nb' * sizeof(uint16_t)).
  23 +
  24 +The function uses the Modbus function code 0x04 (read input registers). The
  25 +holding registers and input registers have different historical meaning, but
  26 +nowadays it's more common to use holding registers only.
  27 +
  28 +
  29 +RETURN VALUE
  30 +------------
  31 +The _modbus_read_input_registers()_ function shall return the number of read
  32 +input registers if successful. Otherwise it shall return -1 and set errno.
  33 +
  34 +
  35 +ERRORS
  36 +------
  37 +EMBMDATA::
  38 +Too many bits requested
  39 +
  40 +
  41 +SEE ALSO
  42 +--------
  43 +linkmb:modbus_read_[3]
  44 +linkmb:modbus_write_bit[3]
  45 +
  46 +
  47 +AUTHORS
  48 +-------
  49 +The libmodbus documentation was written by Stéphane Raimbault
  50 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_read_registers.txt 0 → 100644
  View file @6254ede
  1 +modbus_read_registers(3)
  2 +========================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_read_registers - read many registers
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_read_registers(modbus_t *'ctx', int 'addr', int 'nb', uint16_t *'dest')*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_read_registers()_ function shall read the content of the 'nb'
  18 +holding registers to the address 'addr' of the remote device. The result of
  19 +reading is stored in 'dest' array as word values (16 bits).
  20 +
  21 +You must take care to allocate enough memory to store the results in 'dest'
  22 +(at least 'nb' * sizeof(uint16_t)).
  23 +
  24 +The function uses the Modbus function code 0x03 (read holding registers).
  25 +
  26 +
  27 +RETURN VALUE
  28 +------------
  29 +The _modbus_read_registers()_ function shall return the number of read registers
  30 +if successful. Otherwise it shall return -1 and set errno.
  31 +
  32 +
  33 +ERRORS
  34 +------
  35 +EMBMDATA::
  36 +Too many registers requested
  37 +
  38 +
  39 +SEE ALSO
  40 +--------
  41 +linkmb:modbus_write_register[3]
  42 +linkmb:modbus_write_registers[3]
  43 +
  44 +
  45 +AUTHORS
  46 +-------
  47 +The libmodbus documentation was written by Stéphane Raimbault
  48 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_set_debug.txt 0 → 100644
  View file @6254ede
  1 +modbus_set_debug(3)
  2 +===================
  3 +
  4 +NAME
  5 +----
  6 +modbus_set_debug - set debug flag of the context
  7 +
  8 +
  9 +SYNOPSIS
  10 +--------
  11 +*void modbus_set_debug(*modbus_t 'ctx', int 'boolean');*
  12 +
  13 +
  14 +DESCRIPTION
  15 +-----------
  16 +The _modbus_set_debug()_ function shall set the debug flag of the *modbus_t*
  17 +context by using the argument 'boolean'. When the 'boolean' value is set to
  18 +'TRUE', many verbose messages are displayed on stdout and stderr. For example,
  19 +this flag is useful to display the bytes of the Modbus messages.
  20 +
  21 +[verse]
  22 +___________________
  23 +[00][14][00][00][00][06][12][03][00][6B][00][03]
  24 +Waiting for a confirmation...
  25 +<00><14><00><00><00><09><12><03><06><02><2B><00><00><00><00>
  26 +___________________
  27 +
  28 +
  29 +RETURN VALUE
  30 +------------
  31 +There is no return values.
  32 +
  33 +
  34 +AUTHORS
  35 +-------
  36 +The libmodbus documentation was written by Stéphane Raimbault
  37 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_set_error_recovery.txt 0 → 100644
  View file @6254ede
  1 +modbus_set_error_recovery(3)
  2 +============================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_set_error_recovery - set the error recovery mode
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_set_error_recovery(modbus_t *'ctx', int 'enabled');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_set_error_recovery()_ function shall set the error recovery mode to
  18 +apply when the connection fails.
  19 +
  20 +By default there is no error recovery so the application must check the error
  21 +values returned by libmodbus functions and handle them if necessary.
  22 +
  23 +When enabled, the library will attempt an immediate reconnection which may hang
  24 +for several seconds if the network to the remote target unit is down. The write
  25 +will try a infinite close/connect loop until to be successful and the
  26 +select/read calls will just try to retablish the connection one time then will
  27 +return an error (if the connecton was down, the values to read are certainly not
  28 +available anymore after reconnection, except for slave/server).
  29 +
  30 +It's not recommanded to enable error recovery for slave/server.
  31 +
  32 +
  33 +RETURN VALUE
  34 +------------
  35 +The _modbus_close()_ function shall return 0 if successful. Otherwise it shall
  36 +return -1 and set errno to one of the values defined below.
  37 +
  38 +
  39 +ERRORS
  40 +------
  41 +*EINVAL*::
  42 +The value of the argument 'enabled' is not 'TRUE' of 'FALSE'.
  43 +
  44 +
  45 +AUTHORS
  46 +-------
  47 +The libmodbus documentation was written by Stéphane Raimbault
  48 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_set_slave.txt 0 → 100644
  View file @6254ede
  1 +modbus_set_slave(3)
  2 +===================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_set_slave - set slave number in the context
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_set_slave(modbus_t *'ctx', int 'slave')*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_set_slave()_ function shall set the slave number in the libmodbus
  18 +context.
  19 +
  20 +The behavior depends of network and the role of the device:
  21 +
  22 +*RTU*::
  23 +Define the slave ID of the remote device to talk in master mode or set the
  24 +internal slave ID in slave mode. According to the protocol, a Modbus device must
  25 +only accept message holing its slave number or the special broadcast number.
  26 +
  27 +*TCP*::
  28 +The slave number is only required in TCP if the message must reach a device
  29 +on a serial network. The special value 'MODBUS_TCP_SLAVE' (0xFF) can be used in TCP mode to restore
  30 +the default value.
  31 +
  32 +The broadcast address is 'MODBUS_BROADCAST_ADDRESS'. This special value must be
  33 +use when you want all Modbus devices of the network receive the request.
  34 +
  35 +
  36 +RETURN VALUE
  37 +------------
  38 +The _modbus_set_slave()_ function shall return 0 if successful. Otherwise it
  39 +shall return -1 and set errno to one of the values defined below.
  40 +
  41 +
  42 +ERRORS
  43 +------
  44 +*EINVAL*::
  45 +The slave number is invalid.
  46 +
  47 +
  48 +AUTHORS
  49 +-------
  50 +The libmodbus documentation was written by Stéphane Raimbault
  51 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_set_timeout_begin.txt 0 → 100644
  View file @6254ede
  1 +modbus_set_timeout_begin(3)
  2 +===========================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_set_timeout_begin - set timeout of begin of message
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*void modbus_set_timeout_begin(*modbus_t 'ctx', struct timeval *'timeout');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_set_timeout_begin()_ function shall set the timeout of begin of
  18 +message. If the waiting before receiving a message is longer than the given
  19 +timeout, an error will be raised.
  20 +
  21 +
  22 +RETURN VALUE
  23 +------------
  24 +There is no return values.
  25 +
  26 +
  27 +EXAMPLE
  28 +-------
  29 +[source,c]
  30 +-------------------
  31 +struct timeval timeout_begin_old;
  32 +struct timeval timeout_begin_new;
  33 +
  34 +/* Save original timeout */
  35 +modbus_get_timeout_begin(ctx, &timeout_begin_old);
  36 +
  37 +/* Define a new and too short timeout! */
  38 +timeout_begin_new.tv_sec = 0;
  39 +timeout_begin_new.tv_usec = 0;
  40 +modbus_set_timeout_begin(ctx, &timeout_begin_new);
  41 +-------------------
  42 +
  43 +
  44 +SEE ALSO
  45 +--------
  46 +linkmb:modbus_get_timeout_begin[3]
  47 +linkmb:modbus_get_timeout_end[3]
  48 +linkmb:modbus_set_timeout_end[3]
  49 +
  50 +
  51 +AUTHORS
  52 +-------
  53 +The libmodbus documentation was written by Stéphane Raimbault
  54 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_set_timeout_end.txt 0 → 100644
  View file @6254ede
  1 +modbus_set_timeout_end(3)
  2 +===========================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_set_timeout_end - set timeout of end of message
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*void modbus_set_timeout_end(*modbus_t 'ctx', struct timeval *'timeout');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_set_timeout_end()_ function shall set the timeout of end of
  18 +message. If the delay between the begin and the end of message is longer than
  19 +the given timeout, an error will be raised.
  20 +
  21 +
  22 +RETURN VALUE
  23 +------------
  24 +There is no return values.
  25 +
  26 +
  27 +SEE ALSO
  28 +--------
  29 +linkmb:modbus_get_timeout_begin[3]
  30 +linkmb:modbus_set_timeout_begin[3]
  31 +linkmb:modbus_get_timeout_end[3]
  32 +
  33 +
  34 +AUTHORS
  35 +-------
  36 +The libmodbus documentation was written by Stéphane Raimbault
  37 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_strerror.txt 0 → 100644
  View file @6254ede
  1 +modbus_strerror(3)
  2 +=================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_strerror - return the error message
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*const char *modbus_strerror(*int 'errnum');*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_strerror()_ function shall return a pointer to an error message
  18 +string corresponding to the error number specified by the 'errnum' argument. As
  19 +libmodbus defines additional error numbers over and above those defined by the
  20 +operating system, applications should use _modbus_strerror()_ in preference to
  21 +the standard _strerror()_ function.
  22 +
  23 +
  24 +RETURN VALUE
  25 +------------
  26 +The _modbus_strerror()_ function shall return a pointer to an error message
  27 +string.
  28 +
  29 +
  30 +ERRORS
  31 +------
  32 +No errors are defined.
  33 +
  34 +
  35 +EXAMPLE
  36 +-------
  37 +.Displaying an error message when a Modbus connection cannot be established
  38 +[source,c]
  39 +-------------------
  40 +if (modbus_connect(ctx) == -1) {
  41 + fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
  42 + abort();
  43 +}
  44 +-------------------
  45 +
  46 +SEE ALSO
  47 +--------
  48 +linkmb:libmodbus
  49 +
  50 +
  51 +AUTHORS
  52 +-------
  53 +The libmodbus documentation was written by Stéphane Raimbault
  54 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_write_bit.txt 0 → 100644
  View file @6254ede
  1 +modbus_write_bit(3)
  2 +===================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_write_bit - write a single bit
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_write_bit(modbus_t *'ctx', int 'addr', int 'status')*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_write_bit()_ function shall write the status of 'status' at the
  18 +address 'addr' of the remote device. The value must be set to _TRUE_ or _FALSE_.
  19 +
  20 +The function uses the Modbus function code 0x05 (force single coil).
  21 +
  22 +
  23 +RETURN VALUE
  24 +------------
  25 +The _modbus_write_bit()_ function shall return 1 if successful. Otherwise it
  26 +shall return -1 and set errno.
  27 +
  28 +
  29 +SEE ALSO
  30 +--------
  31 +linkmb:modbus_read_bits[3]
  32 +linkmb:modbus_write_bits[3]
  33 +
  34 +
  35 +AUTHORS
  36 +-------
  37 +The libmodbus documentation was written by Stéphane Raimbault
  38 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_write_bits.txt 0 → 100644
  View file @6254ede
  1 +modbus_write_bits(3)
  2 +====================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_write_bits - write many bits
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_write_bits(modbus_t *'ctx', int 'addr', int 'nb', const uint8_t *'src')*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_write_bits()_ function shall write the status of the 'nb' bits
  18 +(coils) from 'src' at the address 'addr' of the remote device. The
  19 +'src' array must contains bytes set to _TRUE_ or _FALSE_.
  20 +
  21 +The function uses the Modbus function code 0x0F (force multiple coils).
  22 +
  23 +
  24 +RETURN VALUE
  25 +------------
  26 +The _modbus_write_bits()_ function shall return the number of written bits if
  27 +successful. Otherwise it shall return -1 and set errno.
  28 +
  29 +
  30 +ERRORS
  31 +------
  32 +EMBMDATA::
  33 +Writing too many bits
  34 +
  35 +
  36 +SEE ALSO
  37 +--------
  38 +linkmb:modbus_read_bits[3]
  39 +linkmb:modbus_write_bit[3]
  40 +
  41 +
  42 +AUTHORS
  43 +-------
  44 +The libmodbus documentation was written by Stéphane Raimbault
  45 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_write_register.txt 0 → 100644
  View file @6254ede
  1 +modbus_write_register(3)
  2 +========================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_write_register - write a single register
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_write_register(modbus_t *'ctx', int 'addr', int 'value')*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_write_register()_ function shall write the value of 'value'
  18 +holding registers at the address 'addr' of the remote device.
  19 +
  20 +The function uses the Modbus function code 0x06 (preset single register).
  21 +
  22 +
  23 +RETURN VALUE
  24 +------------
  25 +The _modbus_write_register()_ function shall return 1 if successful. Otherwise
  26 +it shall return -1 and set errno.
  27 +
  28 +
  29 +SEE ALSO
  30 +--------
  31 +linkmb:modbus_read_register[3]
  32 +linkmb:modbus_write_registers[3]
  33 +
  34 +
  35 +AUTHORS
  36 +-------
  37 +The libmodbus documentation was written by Stéphane Raimbault
  38 +<stephane.raimbault@gmail.com>
... ...
doc/modbus_write_registers.txt 0 → 100644
  View file @6254ede
  1 +modbus_write_registers(3)
  2 +=========================
  3 +
  4 +
  5 +NAME
  6 +----
  7 +modbus_write_registers - write many registers
  8 +
  9 +
  10 +SYNOPSIS
  11 +--------
  12 +*int modbus_write_registers(modbus_t *'ctx', int 'addr', int 'nb', const uint16_t *'src')*
  13 +
  14 +
  15 +DESCRIPTION
  16 +-----------
  17 +The _modbus_write_registers()_ function shall write the content of the 'nb'
  18 +holding registers from the array 'src' at address 'addr' of the
  19 +remote device.
  20 +
  21 +The function uses the Modbus function code 0x10 (preset multiple registers).
  22 +
  23 +
  24 +RETURN VALUE
  25 +------------
  26 +The _modbus_write_registers()_ function shall return the number of written registers
  27 +if successful. Otherwise it shall return -1 and set errno.
  28 +
  29 +
  30 +SEE ALSO
  31 +--------
  32 +linkmb:modbus_read_register[3]
  33 +linkmb:modbus_write_register[3]
  34 +
  35 +
  36 +AUTHORS
  37 +-------
  38 +The libmodbus documentation was written by Stéphane Raimbault
  39 +<stephane.raimbault@gmail.com>
... ...
src/modbus-tcp.c
  View file @6254ede
... ... @@ -665,6 +665,7 @@ modbus_t* modbus_new_tcp(const char *ip, int port)
665 665 return ctx;
666 666 }
667 667  
  668 +
668 669 modbus_t* modbus_new_tcp_pi(const char *node, const char *service)
669 670 {
670 671 modbus_t *ctx;
... ...