diff --git a/AUTHORS.rst b/AUTHORS.rst index d349f318a..d273c5798 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -1,9 +1,10 @@ Authors ======= -All these version were not possible without volunteers! +All these versions would not be possible without volunteers! This is a complete list for each major version. +A big "thank you" to everybody who helped out. Pymodbus version 3 family ------------------------- diff --git a/CHANGELOG.rst b/CHANGELOG.rst index fa4c3d650..6ad137534 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,8 +1,8 @@ Changelog ========= -All these version would not possible without a lot of work from volunteers! +All these version would not be possible without a lot of work from volunteers! -We, the maintainers, are greatful for all the pull requests small or big, that +We, the maintainers, are greatful for each pull requests small or big, that helps make pymodbus a better product. :ref:`Authors`: contains a complete list of volunteers have contributed to each major version. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.rst similarity index 100% rename from CONTRIBUTING.md rename to CONTRIBUTING.rst diff --git a/MANIFEST.in b/MANIFEST.in index c9da98a9f..2dac93389 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,4 @@ include pyproject.toml -include README.md +include README.rst include CHANGELOG.rst include LICENSE diff --git a/README.md b/README.md deleted file mode 100644 index c8c98c95a..000000000 --- a/README.md +++ /dev/null @@ -1,270 +0,0 @@ -# PyModbus - A Python Modbus Stack - -Pymodbus is a full Modbus protocol implementation using a synchronous or -asynchronous core. The library consist of 4 parts: - -- **client**, connect to your favorite device -- **server**, simulate your favorite device -- **repl**, a text based client/server simulator -- **simulator**, a html based server simulator - -Pymodbus: - -- implement the modbus standard protocol, with the possibility to add - customizations. -- support serial (rs-485), tcp, tls and udp communication. -- support all standard frames: socket, rtu, rtu-over-tcp, tcp and - ascii. -- can be used without any third party dependencies (aside from - pyserial) -- is a very lightweight project. -- requires Python \>= 3.8. -- provides a lot of ready to use examples. -- provides a server/client simulators. -- have a thorough test suite, that test all corners of the library. -- Tested automatically on Windows, Linux and MacOS with python 3.8 - - 3.11 - -The modbus protocol documentation is available -`here <_static/Modbus_Application_Protocol_V1_1b3.pdf>` - -We are constantly working the modernize pymodbus and add new features, -and we look for people who want to help a bit. There are challenges -small and large not only programming but also documentation and testing. - -[![image](https://github.com/pymodbus-dev/pymodbus/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/pymodbus-dev/pymodbus/actions/workflows/ci.yml) - -[![Documentation Status](https://readthedocs.org/projects/pymodbus/badge/?version=latest)](https://pymodbus.readthedocs.io/en/latest/?badge=latest) - -[![Downloads](https://pepy.tech/badge/pymodbus)](https://pepy.tech/project/pymodbus) - -## Supported versions - -Version -[3.5.4](https://github.com/pymodbus-dev/pymodbus/releases/tag/v3.5.4) is -the current release. - -Each release is -[documented](https://pymodbus.readthedocs.io/en/latest/source/changelog.html) - -A big thanks to all the -[volunteers](https://pymodbus.readthedocs.io/en/latest/source/authors.html) -that helped make pymodbus a great project. - -::: important -::: title -Important -::: - -All API changes after 3.0.0 are documented in -[API_changes.rst](https://github.com/pymodbus-dev/pymodbus/blob/dev/CHANGELOG.rst) -::: - -## Common features - -> - Full modbus standard protocol implementation -> - Support for custom function codes -> - Most of the extended protocol -> (diagnostic/file/pipe/setting/information) also implemented -> - TCP, RTU-OVER-TCP, UDP, TLS, Serial ASCII and Serial RTU - -## Client Features - -> - asynchronous and synchronous API for applications -> - Payload builder/decoder utilities -> - Pymodbus REPL for quick tests - -## Server Features - -> - Simulate real life devices -> - asynchronous and synchronous versions -> - Full server control context (device information, counters, etc) -> - A number of backend datastores -> - Pymodbus REPL for quick tests -> - Pymodbus simulator for cloud based testing - -## Use Cases - -The client is the most typically used. It is embedded into applications, -where it abstract the modbus protocol from the application by providing -an easy to use API. The client is integrated into some well known -projects like [home-assistant](https://www.home-assistant.io). - -Although most system administrators will find little need for a Modbus -server on any modern hardware, they may find the need to query devices -on their network for status (PDU, PDR, UPS, etc). Since the library is -written in python, it allows for easy scripting and/or integration into -their existing solutions. - -Continuing, most monitoring software needs to be stress tested against -hundreds or even thousands of devices (why this was originally written), -but getting access to that many is unwieldy at best. - -The pymodbus server will allow a user to test as many devices as their -base operating system will allow. - -For more information please browse the project documentation: - - - -## Example Code - -For those of you that just want to get started fast, here you go: - - from pymodbus.client import ModbusTcpClient - - client = ModbusTcpClient('MyDevice.lan') - client.connect() - client.write_coil(1, True) - result = client.read_coils(1,1) - print(result.bits[0]) - client.close() - -We provide a couple of simple ready to go clients: - -- [async - client](https://github.com/pymodbus-dev/pymodbus/blob/dev/examples/simple_async_client.py) -- [sync - client](https://github.com/pymodbus-dev/pymodbus/blob/dev/examples/simple_sync_client.py) - -For more advanced examples, check out the -[Examples](https://pymodbus.readthedocs.io/en/dev/source/examples.html) -included in the repository. If you have created any utilities that meet -a specific need, feel free to submit them so others can benefit. - - examples -> Essential examples guaranteed to work (tested with our CI) - ├── contrib -> Examples contributed by contributors. - -Also, if you have a question, please [create a post in discussions q&a -topic](https://github.com/pymodbus-dev/pymodbus/discussions/new?category=q-a), -so that others can benefit from the results. - -If you think, that something in the code is broken/not running well, -please [open an -issue](https://github.com/pymodbus-dev/pymodbus/issues/new), read the -Template-text first and then post your issue with your setup -information. - -## Installing with pip - -You can install using pip or easy install by issuing the following -commands in a terminal window (make sure you have correct permissions or -a virtualenv currently running): - -> pip install -U pymodbus - -If you want to use the serial interface: - -> pip install -U pymodbus\[serial\] - -This will install pymodbus, r - -To install pymodbus with options run: - -> pip install -U pymodbus\[\,\...\] - -Available options are: - -- **repl**, install dependencies needed by pymodbus.repl -- **serial**, installs serial drivers. -- **simulator**, install dependencies needed by pymodbus.simulator -- **documentation**, installs tools to generate documentation. -- **development**, installs development tools needed to enable - test/check of pymodbus changes. -- **all**, installs all of the above - -## Installing with github - -Before cloning the repo, you need to install python3 (preferable 3.11) -and make and activate a virtual environment: - - python3 -m venv /path/to/new/virtual/environment - - source .venv/bin/activate - -Clone the source and install from there: - - git clone git://github.com/pymodbus-dev/pymodbus.git - cd pymodbus - -To get a specific release: - - git checkout v3.5.2 - -To get bleeding edge: - - git checkout dev - -Install required development tools: - - pip install -e ".[development]" - - pre-commit install - -This installs pymodbus in your virtual environment with pointers -directly to the pymodbus directory, so any change you make is -immediately available as if installed. It will also install -[pre-commit]{.title-ref} git hooks. - -The repository contains a number of important branches and tags. - -: - **dev** is where all development happens, this branch is not - always stable. - - **master** is where are releases are kept. - - All releases are tagged with **vX.Y.Z** (e.g. v2.5.3) - -If a maintenance release of an old version is needed (e.g. v2.5.4), the -release tag is used to create a branch with the same name, and -maintenance development is merged here. - -## Current Work In Progress - -The maintenance team is very small with limited capacity and few modbus -devices. - -If your company would like your device tested or have a cloud based -device simulation, feel free to contact us. We are happy to help your -company solve your modbus challenges. - -That said, the current work mainly involves polishing the library and -solving issues: - -> - Fixing bugs/feature requests -> - Architecture documentation -> - Functional testing against any reference we can find -> - The remaining edges of the protocol (that we think no one uses) - -There are 2 bigger projects ongoing: - -> - rewriting the internal part of all clients (both sync and async) -> - Make the simulator datastore THE datastore - -## Development Instructions - -The current code base is compatible python \>= 3.8. Here are some of the -common commands to perform a range of activities - -> ./check_ci.sh run the same checks as CI runs on a pull request. - -## Generate documentation - -**Remark** Assumes that you have installed documentation tools: - -> pip install -e \".\[documentation\]\" - -to build do: - -> cd doc ./build_html - -The documentation is available in \/build/html/html - -## Contributing - -Just fork the repo and raise your PR against [dev]{.title-ref} branch. - -We always have more work than time, so feel free to open a discussion / -issue on a theme you want to solve. - -## License Information - -Released under the [BSD License](LICENSE) diff --git a/README.rst b/README.rst index 37f3f8b17..a0db7b656 100644 --- a/README.rst +++ b/README.rst @@ -1,31 +1,5 @@ PyModbus - A Python Modbus Stack ================================ -Pymodbus is a full Modbus protocol implementation using a synchronous or asynchronous core. -The library consist of 4 parts: - -- **client**, connect to your favorite device -- **server**, simulate your favorite device -- **repl**, a text based client/server simulator -- **simulator**, a html based server simulator - -Pymodbus: - -- implement the modbus standard protocol, with the possibility to add customizations. -- support serial (rs-485), tcp, tls and udp communication. -- support all standard frames: socket, rtu, rtu-over-tcp, tcp and ascii. -- can be used without any third party dependencies (aside from pyserial) -- is a very lightweight project. -- requires Python >= 3.8. -- provides a lot of ready to use examples. -- provides a server/client simulators. -- have a thorough test suite, that test all corners of the library. -- Tested automatically on Windows, Linux and MacOS with python 3.8 - 3.11 - -The modbus protocol documentation is available :download:`here <_static/Modbus_Application_Protocol_V1_1b3.pdf>` - - -We are constantly working the modernize pymodbus and add new features, and we look for people who want to help a bit. -There are challenges small and large not only programming but also documentation and testing. .. image:: https://github.com/pymodbus-dev/pymodbus/actions/workflows/ci.yml/badge.svg?branch=dev :target: https://github.com/pymodbus-dev/pymodbus/actions/workflows/ci.yml @@ -36,41 +10,89 @@ There are challenges small and large not only programming but also documentation :target: https://pepy.tech/project/pymodbus :alt: Downloads +Pymodbus is a full Modbus protocol implementation offering client/server with synchronous/asynchronous API a well as simulators. + Supported versions ------------------ -Version `3.5.4 `_ is the current release. +Current release is `3.5.4 `_. +All changes are `detailed `_ +and all API changes are `documented `_ -Each release is `documented `_ +A big thanks to all the `volunteers `_ that helps make pymodbus a great project. -A big thanks to all the `volunteers `_ that helped make pymodbus a great project. +Source code on `github `_ -.. important:: - All API changes after 3.0.0 are documented in `API_changes.rst `_ +Pymodbus in a nutshell +---------------------- + +Pymodbus consist of 5 parts: +- **client**, connect to your favorite device(s) +- **server**, simulate your favorite device(s) +- **repl**, a commandline text based client/server simulator +- **simulator**, an html based server simulator +- **examples**, showing both simple and advances usage Common features ---------------- - * Full modbus standard protocol implementation - * Support for custom function codes - * Most of the extended protocol (diagnostic/file/pipe/setting/information) also implemented - * TCP, RTU-OVER-TCP, UDP, TLS, Serial ASCII and Serial RTU +^^^^^^^^^^^^^^^ + +* Full :download:`modbus standard protocol <_static/Modbus_Application_Protocol_V1_1b3.pdf>` implementation +* Support for custom function codes +* support serial (rs-485), tcp, tls and udp communication +* support all standard frames: socket, rtu, rtu-over-tcp, tcp and ascii +* does not have third party dependencies, apart from pyserial (optional) +* very lightweight project +* requires Python >= 3.8 +* thorough test suite, that test all corners of the library +* automatically tested on Windows, Linux and MacOS combined with python 3.8 - 3.12 +* strongly typed API (py.typed present) + Client Features ---------------- - * asynchronous and synchronous API for applications - * Payload builder/decoder utilities - * Pymodbus REPL for quick tests +^^^^^^^^^^^^^^^ + +* asynchronous API and synchronous API for applications +* very simple setup and call sequence (just 6 lines of code) +* utilities to convert int/float to/from multiple registers +* payload builder/decoder to help with complex data + +`Client documentation `_ Server Features ---------------- - * Simulate real life devices - * asynchronous and synchronous versions - * Full server control context (device information, counters, etc) - * A number of backend datastores - * Pymodbus REPL for quick tests - * Pymodbus simulator for cloud based testing +^^^^^^^^^^^^^^^ + +* asynchronous implementation for high performance +* synchronous API classes for convenience +* simulate real life devices +* full server control context (device information, counters, etc) +* different backend datastores to manage register values +* callback to intercept requests/responses +* work on RS485 in parallel with other devices + +`Server documentation `_ + + +REPL Features +^^^^^^^^^^^^^ + +- server/client commandline emulator +- easy test of real device (client) +- easy test of client app (server) +- simulation of broken requests/responses +- simulation of error responses (hard to provoke in real devices) + + +Simulator Features +^^^^^^^^^^^^^^^^^^ + +- server simulator with WEB interface +- configure the structure of a real device +- monitor traffic online +- allow distributed team members to work on a virtual device using internet +- simulation of broken requests/responses +- simulation of error responses (hard to provoke in real devices) Use Cases --------- @@ -80,143 +102,163 @@ easy to use API. The client is integrated into some well known projects like `home-assistant `_. Although most system administrators will find little need for a Modbus -server on any modern hardware, they may find the need to query devices on -their network for status (PDU, PDR, UPS, etc). Since the library is written -in python, it allows for easy scripting and/or integration into their existing -solutions. - -Continuing, most monitoring software needs to be stress tested against -hundreds or even thousands of devices (why this was originally written), but -getting access to that many is unwieldy at best. +server, the server is handy to verify the functionality of an application. -The pymodbus server will allow a user to test as many devices as their -base operating system will allow. +The simulator and/or server is often used to simulate real life devices testing +applications. The server is excellent to perform high volume testing (e.g. +houndreds of devices connected to the application). The advantage of the server is +that it runs not only a "normal" computers but also on small ones like Raspberry PI. +Since the library is written in python, it allows for easy scripting and/or integration into their existing +solutions. For more information please browse the project documentation: https://readthedocs.org/docs/pymodbus/en/latest/index.html -Example Code ------------- -For those of you that just want to get started fast, here you go:: - from pymodbus.client import ModbusTcpClient +Installation +------------ - client = ModbusTcpClient('MyDevice.lan') - client.connect() - client.write_coil(1, True) - result = client.read_coils(1,1) - print(result.bits[0]) - client.close() +The library is available on pypi.org and github.com to install with -We provide a couple of simple ready to go clients: +- **`pip`** for those who just want to use the library +- **`git clone`** for those who wants to help or just are curious -- `async client `_ -- `sync client `_ +Be aware that there are a number of project, who have forked pymodbus and -For more advanced examples, check out the `Examples `_ included in the -repository. If you have created any utilities that meet a specific -need, feel free to submit them so others can benefit. +- seems just to provide a version frozen in time +- extended pymodbus with extra functionality -:: +The latter is not because we rejected the extra functionality (we welcome all changes), +but because the codeowners made that decision. - examples -> Essential examples guaranteed to work (tested with our CI) - ├── contrib -> Examples contributed by contributors. +In both cases, please understand, we cannot offer support to users of these projects as we do not known +what have been changed nor what status the forked code have. +A growing number of Linux distributions include pymodbus in their standard installation. -Also, if you have a question, please `create a post in discussions q&a topic `_, -so that others can benefit from the results. +You need to have python3 installed, preferable 3.11. -If you think, that something in the code is broken/not running well, please `open an issue `_, -read the Template-text first and then post your issue with your setup information. +Installing with pip +^^^^^^^^^^^^^^^^^^^ +You can install using pip by issuing the following +commands in a terminal window:: -Installing with pip -------------------- + pip install pymodbus -You can install using pip or easy install by issuing the following -commands in a terminal window (make sure you have correct -permissions or a virtualenv currently running): +If you want to use the serial interface:: - pip install -U pymodbus + pip install pymodbus[serial] -If you want to use the serial interface: +This will install pymodbus with the pyserial dependency. - pip install -U pymodbus[serial] +Pymodbus offers a number of extra options: -This will install pymodbus, r +- **repl**, needed by pymodbus.repl -To install pymodbus with options run: +- **serial**, needed for serial communication - pip install -U pymodbus[