PyModbus - A Python Modbus Stack
================================
.. 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
.. image:: https://readthedocs.org/projects/pymodbus/badge/?version=latest
:target: https://pymodbus.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://pepy.tech/badge/pymodbus
: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.
Current release is `3.6.8 <https://github.com/pymodbus-dev/pymodbus/releases/tag/v3.6.8>`_.
Bleeding edge (not released) is `dev <https://github.com/pymodbus-dev/pymodbus/tree/dev>`_.
All changes are described in `release notes <https://pymodbus.readthedocs.io/en/latest/source/changelog.html>`_
and all API changes are `documented <https://pymodbus.readthedocs.io/en/latest/source/api_changes.html>`_
A big thanks to all the `volunteers <https://pymodbus.readthedocs.io/en/latest/source/authors.html>`_ that helps make pymodbus a great project.
Source code on `github <https://github.com/pymodbus-dev/pymodbus>`_
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
* 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)
The modbus protocol specification: Modbus_Application_Protocol_V1_1b3.pdf can be found on
`modbus org <https://modbus.org>`_
Client Features
^^^^^^^^^^^^^^^
* 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 <https://pymodbus.readthedocs.io/en/latest/source/client.html>`_
Server Features
^^^^^^^^^^^^^^^
* 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 <https://pymodbus.readthedocs.io/en/latest/source/library/server.html>`_
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)
`REPL documentation <https://github.com/pymodbus-dev/repl>`_
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)
`Simulator documentation <https://pymodbus.readthedocs.io/en/dev/source/simulator.html>`_
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, the server is handy to verify the functionality of an application.
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
Install
-------
The library is available on pypi.org and github.com to install with
- :code:`pip` for those who just want to use the library
- :code:`git clone` for those who wants to help or just are curious
Be aware that there are a number of project, who have forked pymodbus and
- 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.
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.
You need to have python3 installed, preferable 3.11.
Install with pip
^^^^^^^^^^^^^^^^
You can install using pip by issuing the following
commands in a terminal window::
pip install pymodbus
If you want to use the serial interface::
pip install pymodbus[serial]
This will install pymodbus with the pyserial dependency.
Pymodbus offers a number of extra options:
- **repl**, needed by pymodbus.repl
- **serial**, needed for serial communication
- **simulator**, needed by pymodbus.simulator
- **documentation**, needed to generate documentation
- **development**, needed for development
- **all**, installs all of the above
which can be installed as::
pip install pymodbus[<option>,...]
It is possible to install old releases if needed::
pip install pymodbus==3.5.4
Install with github
^^^^^^^^^^^^^^^^^^^
On github, fork https://github.com/pymodbus-dev/pymodbus.git
Clone the source, and make a virtual environment::
git clone git://github.com/<your account>/pymodbus.git
cd pymodbus
python3 -m venv .venv
Activate the virtual environment, this command needs repeated in every new terminal::
source .venv/bin/activate
To get a specific release::
git checkout v3.5.2
or the bleeding edge::
git checkout dev
Some distributions have an old pip, which needs to be upgraded:
pip install --upgrade pip
Install required development tools::
pip install ".[development]"
Install all (allows creation of documentation etc):
pip install ".[all]"
Install git hooks, that helps control the commit and avoid errors when submitting a Pull Request:
cp githooks/* .git/hooks
This installs dependencies in your virtual environment
with pointers directly to the pymodbus directory,
so any change you make is immediately available as if installed.
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.
* **vX.Y.Z** (e.g. v2.5.3) is a specific release
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 `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.
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.
`Example documentation <https://pymodbus.readthedocs.io/en/dev/source/examples.html>`_
Contributing
------------
Just fork the repo and raise your Pull Request against :code:`dev` branch.
We always have more work than time, so feel free to open a discussion / issue on a theme you want to solve.
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
There are 2 bigger projects ongoing:
* rewriting the internal part of all clients (both sync and async)
* Add features to and simulator, and enhance the web design
Development instructions
------------------------
The current code base is compatible with python >= 3.8.
Here are some of the common commands to perform a range of activities::
source .venv/bin/activate <-- Activate the virtual environment
./check_ci.sh <-- run the same checks as CI runs on a pull request.
Make a pull request::
git checkout dev <-- activate development branch
git pull <-- update branch with newest changes
git checkout -b feature <-- make new branch for pull request
... make source changes
git commit <-- commit change to git
git push <-- push to your account on github
on github open a pull request, check that CI turns green and then wait for review comments.
Test your changes::
cd test
pytest
you can also do extended testing::
pytest --cov <-- Coverage html report in build/html
pytest --profile <-- Call profile report in prof
Internals
^^^^^^^^^
There are no documentation of the architecture (help is welcome), but most classes and
methods are documented:
`Pymodbus internals <https://pymodbus.readthedocs.io/en/dev/source/internals.html>`_
Generate documentation
^^^^^^^^^^^^^^^^^^^^^^
**Remark** Assumes that you have installed documentation tools:;
pip install ".[documentation]"
to build do::
cd doc
./build_html
The documentation is available in <root>/build/html
Remark: this generates a new zip/tgz file of examples which are uploaded.
License Information
-------------------
Released under the `BSD License <https://github.com/pymodbus-dev/pymodbus/blob/dev/LICENSE>`_
Raw data
{
"_id": null,
"home_page": null,
"name": "pymodbus",
"maintainer": "dhoomakethu, janiversen",
"docs_url": "https://pythonhosted.org/pymodbus/",
"requires_python": ">=3.8.0",
"maintainer_email": null,
"keywords": "modbus, asyncio, scada, client, server, simulator",
"author": "Galen Collins, Jan Iversen",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/62/c1/f18b090dcc45d34b6a0e3563acde71b407ef96a36fa965c508a84f755355/pymodbus-3.6.8.tar.gz",
"platform": "'Linux'",
"description": "PyModbus - A Python Modbus Stack\n================================\n.. image:: https://github.com/pymodbus-dev/pymodbus/actions/workflows/ci.yml/badge.svg?branch=dev\n :target: https://github.com/pymodbus-dev/pymodbus/actions/workflows/ci.yml\n.. image:: https://readthedocs.org/projects/pymodbus/badge/?version=latest\n :target: https://pymodbus.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n.. image:: https://pepy.tech/badge/pymodbus\n :target: https://pepy.tech/project/pymodbus\n :alt: Downloads\n\nPymodbus is a full Modbus protocol implementation offering client/server with synchronous/asynchronous API a well as simulators.\n\nCurrent release is `3.6.8 <https://github.com/pymodbus-dev/pymodbus/releases/tag/v3.6.8>`_.\n\nBleeding edge (not released) is `dev <https://github.com/pymodbus-dev/pymodbus/tree/dev>`_.\n\nAll changes are described in `release notes <https://pymodbus.readthedocs.io/en/latest/source/changelog.html>`_\nand all API changes are `documented <https://pymodbus.readthedocs.io/en/latest/source/api_changes.html>`_\n\nA big thanks to all the `volunteers <https://pymodbus.readthedocs.io/en/latest/source/authors.html>`_ that helps make pymodbus a great project.\n\nSource code on `github <https://github.com/pymodbus-dev/pymodbus>`_\n\nPymodbus in a nutshell\n----------------------\nPymodbus consist of 5 parts:\n\n- **client**, connect to your favorite device(s)\n- **server**, simulate your favorite device(s)\n- **repl**, a commandline text based client/server simulator\n- **simulator**, an html based server simulator\n- **examples**, showing both simple and advances usage\n\nCommon features\n^^^^^^^^^^^^^^^\n* Full modbus standard protocol implementation\n* Support for custom function codes\n* support serial (rs-485), tcp, tls and udp communication\n* support all standard frames: socket, rtu, rtu-over-tcp, tcp and ascii\n* does not have third party dependencies, apart from pyserial (optional)\n* very lightweight project\n* requires Python >= 3.8\n* thorough test suite, that test all corners of the library\n* automatically tested on Windows, Linux and MacOS combined with python 3.8 - 3.12\n* strongly typed API (py.typed present)\n\nThe modbus protocol specification: Modbus_Application_Protocol_V1_1b3.pdf can be found on\n`modbus org <https://modbus.org>`_\n\n\nClient Features\n^^^^^^^^^^^^^^^\n* asynchronous API and synchronous API for applications\n* very simple setup and call sequence (just 6 lines of code)\n* utilities to convert int/float to/from multiple registers\n* payload builder/decoder to help with complex data\n\n`Client documentation <https://pymodbus.readthedocs.io/en/latest/source/client.html>`_\n\n\nServer Features\n^^^^^^^^^^^^^^^\n* asynchronous implementation for high performance\n* synchronous API classes for convenience\n* simulate real life devices\n* full server control context (device information, counters, etc)\n* different backend datastores to manage register values\n* callback to intercept requests/responses\n* work on RS485 in parallel with other devices\n\n`Server documentation <https://pymodbus.readthedocs.io/en/latest/source/library/server.html>`_\n\n\nREPL Features\n^^^^^^^^^^^^^\n- server/client commandline emulator\n- easy test of real device (client)\n- easy test of client app (server)\n- simulation of broken requests/responses\n- simulation of error responses (hard to provoke in real devices)\n\n`REPL documentation <https://github.com/pymodbus-dev/repl>`_\n\n\nSimulator Features\n^^^^^^^^^^^^^^^^^^\n- server simulator with WEB interface\n- configure the structure of a real device\n- monitor traffic online\n- allow distributed team members to work on a virtual device using internet\n- simulation of broken requests/responses\n- simulation of error responses (hard to provoke in real devices)\n\n`Simulator documentation <https://pymodbus.readthedocs.io/en/dev/source/simulator.html>`_\n\nUse Cases\n---------\nThe client is the most typically used. It is embedded into applications,\nwhere it abstract the modbus protocol from the application by providing an\neasy to use API. The client is integrated into some well known projects like\n`home-assistant <https://www.home-assistant.io>`_.\n\nAlthough most system administrators will find little need for a Modbus\nserver, the server is handy to verify the functionality of an application.\n\nThe simulator and/or server is often used to simulate real life devices testing\napplications. The server is excellent to perform high volume testing (e.g.\nhoundreds of devices connected to the application). The advantage of the server is\nthat it runs not only a \"normal\" computers but also on small ones like Raspberry PI.\n\nSince the library is written in python, it allows for easy scripting and/or integration into their existing\nsolutions.\n\nFor more information please browse the project documentation:\n\nhttps://readthedocs.org/docs/pymodbus/en/latest/index.html\n\n\n\nInstall\n-------\nThe library is available on pypi.org and github.com to install with\n\n- :code:`pip` for those who just want to use the library\n- :code:`git clone` for those who wants to help or just are curious\n\nBe aware that there are a number of project, who have forked pymodbus and\n\n- seems just to provide a version frozen in time\n- extended pymodbus with extra functionality\n\nThe latter is not because we rejected the extra functionality (we welcome all changes),\nbut because the codeowners made that decision.\n\nIn both cases, please understand, we cannot offer support to users of these projects as we do not known\nwhat have been changed nor what status the forked code have.\n\nA growing number of Linux distributions include pymodbus in their standard installation.\n\nYou need to have python3 installed, preferable 3.11.\n\nInstall with pip\n^^^^^^^^^^^^^^^^\nYou can install using pip by issuing the following\ncommands in a terminal window::\n\n pip install pymodbus\n\nIf you want to use the serial interface::\n\n pip install pymodbus[serial]\n\nThis will install pymodbus with the pyserial dependency.\n\nPymodbus offers a number of extra options:\n\n- **repl**, needed by pymodbus.repl\n- **serial**, needed for serial communication\n- **simulator**, needed by pymodbus.simulator\n- **documentation**, needed to generate documentation\n- **development**, needed for development\n- **all**, installs all of the above\n\nwhich can be installed as::\n\n pip install pymodbus[<option>,...]\n\nIt is possible to install old releases if needed::\n\n pip install pymodbus==3.5.4\n\n\nInstall with github\n^^^^^^^^^^^^^^^^^^^\nOn github, fork https://github.com/pymodbus-dev/pymodbus.git\n\nClone the source, and make a virtual environment::\n\n\n git clone git://github.com/<your account>/pymodbus.git\n cd pymodbus\n python3 -m venv .venv\n\nActivate the virtual environment, this command needs repeated in every new terminal::\n\n source .venv/bin/activate\n\nTo get a specific release::\n\n git checkout v3.5.2\n\nor the bleeding edge::\n\n git checkout dev\n\nSome distributions have an old pip, which needs to be upgraded:\n\n pip install --upgrade pip\n\nInstall required development tools::\n\n pip install \".[development]\"\n\nInstall all (allows creation of documentation etc):\n\n pip install \".[all]\"\n\nInstall git hooks, that helps control the commit and avoid errors when submitting a Pull Request:\n\n cp githooks/* .git/hooks\n\nThis installs dependencies in your virtual environment\nwith pointers directly to the pymodbus directory,\nso any change you make is immediately available as if installed.\n\nThe repository contains a number of important branches and tags.\n * **dev** is where all development happens, this branch is not always stable.\n * **master** is where are releases are kept.\n * **vX.Y.Z** (e.g. v2.5.3) is a specific release\n\n\nExample Code\n------------\nFor those of you that just want to get started fast, here you go::\n\n from pymodbus.client import ModbusTcpClient\n\n client = ModbusTcpClient('MyDevice.lan')\n client.connect()\n client.write_coil(1, True)\n result = client.read_coils(1,1)\n print(result.bits[0])\n client.close()\n\nWe provide a couple of simple ready to go clients:\n\n- `async client <https://github.com/pymodbus-dev/pymodbus/blob/dev/examples/simple_async_client.py>`_\n- `sync client <https://github.com/pymodbus-dev/pymodbus/blob/dev/examples/simple_sync_client.py>`_\n\nFor more advanced examples, check out `Examples <https://pymodbus.readthedocs.io/en/dev/source/examples.html>`_ included in the\nrepository. If you have created any utilities that meet a specific\nneed, feel free to submit them so others can benefit.\n\nAlso, 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>`_,\nso that others can benefit from the results.\n\nIf you think, that something in the code is broken/not running well, please `open an issue <https://github.com/pymodbus-dev/pymodbus/issues/new>`_,\nread the Template-text first and then post your issue with your setup information.\n\n`Example documentation <https://pymodbus.readthedocs.io/en/dev/source/examples.html>`_\n\n\nContributing\n------------\nJust fork the repo and raise your Pull Request against :code:`dev` branch.\n\nWe always have more work than time, so feel free to open a discussion / issue on a theme you want to solve.\n\nIf your company would like your device tested or have a cloud based device\nsimulation, feel free to contact us.\nWe are happy to help your company solve your modbus challenges.\n\nThat said, the current work mainly involves polishing the library and\nsolving issues:\n\n* Fixing bugs/feature requests\n* Architecture documentation\n* Functional testing against any reference we can find\n\nThere are 2 bigger projects ongoing:\n\n * rewriting the internal part of all clients (both sync and async)\n * Add features to and simulator, and enhance the web design\n\n\nDevelopment instructions\n------------------------\nThe current code base is compatible with python >= 3.8.\n\nHere are some of the common commands to perform a range of activities::\n\n source .venv/bin/activate <-- Activate the virtual environment\n ./check_ci.sh <-- run the same checks as CI runs on a pull request.\n\n\nMake a pull request::\n\n git checkout dev <-- activate development branch\n git pull <-- update branch with newest changes\n git checkout -b feature <-- make new branch for pull request\n ... make source changes\n git commit <-- commit change to git\n git push <-- push to your account on github\n\n on github open a pull request, check that CI turns green and then wait for review comments.\n\nTest your changes::\n\n cd test\n pytest\n\nyou can also do extended testing::\n\n pytest --cov <-- Coverage html report in build/html\n pytest --profile <-- Call profile report in prof\n\nInternals\n^^^^^^^^^\n\nThere are no documentation of the architecture (help is welcome), but most classes and\nmethods are documented:\n\n`Pymodbus internals <https://pymodbus.readthedocs.io/en/dev/source/internals.html>`_\n\n\nGenerate documentation\n^^^^^^^^^^^^^^^^^^^^^^\n\n**Remark** Assumes that you have installed documentation tools:;\n\n pip install \".[documentation]\"\n\nto build do::\n\n cd doc\n ./build_html\n\nThe documentation is available in <root>/build/html\n\nRemark: this generates a new zip/tgz file of examples which are uploaded.\n\n\nLicense Information\n-------------------\n\nReleased under the `BSD License <https://github.com/pymodbus-dev/pymodbus/blob/dev/LICENSE>`_\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A fully featured modbus protocol stack in python",
"version": "3.6.8",
"project_urls": {
"Bug Reports": "https://github.com/pymodbus-dev/pymodbus/issues",
"Discord": "https://discord.gg/vcP8qAz2",
"Docs: Dev": "https://pymodbus.readthedocs.io/en/latest/?badge=latest",
"Homepage": "https://github.com/pymodbus-dev/pymodbus/",
"Source Code": "https://github.com/pymodbus-dev/pymodbus"
},
"split_keywords": [
"modbus",
" asyncio",
" scada",
" client",
" server",
" simulator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3519a9d16f74548d6750acf6604fa74c2cd165b5bc955fe021bf5e1fa04acf14",
"md5": "f7748977166eaa6f91911f61a9fbed21",
"sha256": "8d55d1eaa8b7216d5da7492f5b610e8154d5d3bf6f4a5b3080319fd2c33b59b9"
},
"downloads": -1,
"filename": "pymodbus-3.6.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f7748977166eaa6f91911f61a9fbed21",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 185413,
"upload_time": "2024-04-14T08:23:21",
"upload_time_iso_8601": "2024-04-14T08:23:21.209223Z",
"url": "https://files.pythonhosted.org/packages/35/19/a9d16f74548d6750acf6604fa74c2cd165b5bc955fe021bf5e1fa04acf14/pymodbus-3.6.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "62c1f18b090dcc45d34b6a0e3563acde71b407ef96a36fa965c508a84f755355",
"md5": "809260ecaaef548c7ac327755d7d2d25",
"sha256": "abb214716b56fc62bc0d5d9d964e2249439341746287e918d175f0e3ee241407"
},
"downloads": -1,
"filename": "pymodbus-3.6.8.tar.gz",
"has_sig": false,
"md5_digest": "809260ecaaef548c7ac327755d7d2d25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0",
"size": 191916,
"upload_time": "2024-04-14T08:23:23",
"upload_time_iso_8601": "2024-04-14T08:23:23.099096Z",
"url": "https://files.pythonhosted.org/packages/62/c1/f18b090dcc45d34b6a0e3563acde71b407ef96a36fa965c508a84f755355/pymodbus-3.6.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-14 08:23:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pymodbus-dev",
"github_project": "pymodbus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pymodbus"
}
JSON
