|
| 1 | +# PyModbus - A Python Modbus Stack |
| 2 | + |
| 3 | +Pymodbus is a full Modbus protocol implementation using a synchronous or |
| 4 | +asynchronous core. The library consist of 4 parts: |
| 5 | + |
| 6 | +- **client**, connect to your favorite device |
| 7 | +- **server**, simulate your favorite device |
| 8 | +- **repl**, a text based client/server simulator |
| 9 | +- **simulator**, a html based server simulator |
| 10 | + |
| 11 | +Pymodbus: |
| 12 | + |
| 13 | +- implement the modbus standard protocol, with the possibility to add |
| 14 | + customizations. |
| 15 | +- support serial (rs-485), tcp, tls and udp communication. |
| 16 | +- support all standard frames: socket, rtu, rtu-over-tcp, tcp and |
| 17 | + ascii. |
| 18 | +- can be used without any third party dependencies (aside from |
| 19 | + pyserial) |
| 20 | +- is a very lightweight project. |
| 21 | +- requires Python \>= 3.8. |
| 22 | +- provides a lot of ready to use examples. |
| 23 | +- provides a server/client simulators. |
| 24 | +- have a thorough test suite, that test all corners of the library. |
| 25 | +- Tested automatically on Windows, Linux and MacOS with python 3.8 - |
| 26 | + 3.11 |
| 27 | + |
| 28 | +The modbus protocol documentation is available |
| 29 | +`here <_static/Modbus_Application_Protocol_V1_1b3.pdf>` |
| 30 | + |
| 31 | +We are constantly working the modernize pymodbus and add new features, |
| 32 | +and we look for people who want to help a bit. There are challenges |
| 33 | +small and large not only programming but also documentation and testing. |
| 34 | + |
| 35 | +[](https://github.com/pymodbus-dev/pymodbus/actions/workflows/ci.yml) |
| 36 | + |
| 37 | +[](https://pymodbus.readthedocs.io/en/latest/?badge=latest) |
| 38 | + |
| 39 | +[](https://pepy.tech/project/pymodbus) |
| 40 | + |
| 41 | +## Supported versions |
| 42 | + |
| 43 | +Version |
| 44 | +[3.5.4](https://github.com/pymodbus-dev/pymodbus/releases/tag/v3.5.4) is |
| 45 | +the current release. |
| 46 | + |
| 47 | +Each release is |
| 48 | +[documented](https://pymodbus.readthedocs.io/en/latest/source/changelog.html) |
| 49 | + |
| 50 | +A big thanks to all the |
| 51 | +[volunteers](https://pymodbus.readthedocs.io/en/latest/source/authors.html) |
| 52 | +that helped make pymodbus a great project. |
| 53 | + |
| 54 | +::: important |
| 55 | +::: title |
| 56 | +Important |
| 57 | +::: |
| 58 | + |
| 59 | +All API changes after 3.0.0 are documented in |
| 60 | +[API_changes.rst](https://github.com/pymodbus-dev/pymodbus/blob/dev/CHANGELOG.rst) |
| 61 | +::: |
| 62 | + |
| 63 | +## Common features |
| 64 | + |
| 65 | +> - Full modbus standard protocol implementation |
| 66 | +> - Support for custom function codes |
| 67 | +> - Most of the extended protocol |
| 68 | +> (diagnostic/file/pipe/setting/information) also implemented |
| 69 | +> - TCP, RTU-OVER-TCP, UDP, TLS, Serial ASCII and Serial RTU |
| 70 | +
|
| 71 | +## Client Features |
| 72 | + |
| 73 | +> - asynchronous and synchronous API for applications |
| 74 | +> - Payload builder/decoder utilities |
| 75 | +> - Pymodbus REPL for quick tests |
| 76 | +
|
| 77 | +## Server Features |
| 78 | + |
| 79 | +> - Simulate real life devices |
| 80 | +> - asynchronous and synchronous versions |
| 81 | +> - Full server control context (device information, counters, etc) |
| 82 | +> - A number of backend datastores |
| 83 | +> - Pymodbus REPL for quick tests |
| 84 | +> - Pymodbus simulator for cloud based testing |
| 85 | +
|
| 86 | +## Use Cases |
| 87 | + |
| 88 | +The client is the most typically used. It is embedded into applications, |
| 89 | +where it abstract the modbus protocol from the application by providing |
| 90 | +an easy to use API. The client is integrated into some well known |
| 91 | +projects like [home-assistant](https://www.home-assistant.io). |
| 92 | + |
| 93 | +Although most system administrators will find little need for a Modbus |
| 94 | +server on any modern hardware, they may find the need to query devices |
| 95 | +on their network for status (PDU, PDR, UPS, etc). Since the library is |
| 96 | +written in python, it allows for easy scripting and/or integration into |
| 97 | +their existing solutions. |
| 98 | + |
| 99 | +Continuing, most monitoring software needs to be stress tested against |
| 100 | +hundreds or even thousands of devices (why this was originally written), |
| 101 | +but getting access to that many is unwieldy at best. |
| 102 | + |
| 103 | +The pymodbus server will allow a user to test as many devices as their |
| 104 | +base operating system will allow. |
| 105 | + |
| 106 | +For more information please browse the project documentation: |
| 107 | + |
| 108 | +<https://readthedocs.org/docs/pymodbus/en/latest/index.html> |
| 109 | + |
| 110 | +## Example Code |
| 111 | + |
| 112 | +For those of you that just want to get started fast, here you go: |
| 113 | + |
| 114 | + from pymodbus.client import ModbusTcpClient |
| 115 | + |
| 116 | + client = ModbusTcpClient('MyDevice.lan') |
| 117 | + client.connect() |
| 118 | + client.write_coil(1, True) |
| 119 | + result = client.read_coils(1,1) |
| 120 | + print(result.bits[0]) |
| 121 | + client.close() |
| 122 | + |
| 123 | +We provide a couple of simple ready to go clients: |
| 124 | + |
| 125 | +- [async |
| 126 | + client](https://github.com/pymodbus-dev/pymodbus/blob/dev/examples/simple_async_client.py) |
| 127 | +- [sync |
| 128 | + client](https://github.com/pymodbus-dev/pymodbus/blob/dev/examples/simple_sync_client.py) |
| 129 | + |
| 130 | +For more advanced examples, check out the |
| 131 | +[Examples](https://pymodbus.readthedocs.io/en/dev/source/examples.html) |
| 132 | +included in the repository. If you have created any utilities that meet |
| 133 | +a specific need, feel free to submit them so others can benefit. |
| 134 | + |
| 135 | + examples -> Essential examples guaranteed to work (tested with our CI) |
| 136 | + ├── contrib -> Examples contributed by contributors. |
| 137 | + |
| 138 | +Also, if you have a question, please [create a post in discussions q&a |
| 139 | +topic](https://github.com/pymodbus-dev/pymodbus/discussions/new?category=q-a), |
| 140 | +so that others can benefit from the results. |
| 141 | + |
| 142 | +If you think, that something in the code is broken/not running well, |
| 143 | +please [open an |
| 144 | +issue](https://github.com/pymodbus-dev/pymodbus/issues/new), read the |
| 145 | +Template-text first and then post your issue with your setup |
| 146 | +information. |
| 147 | + |
| 148 | +## Installing with pip |
| 149 | + |
| 150 | +You can install using pip or easy install by issuing the following |
| 151 | +commands in a terminal window (make sure you have correct permissions or |
| 152 | +a virtualenv currently running): |
| 153 | + |
| 154 | +> pip install -U pymodbus |
| 155 | +
|
| 156 | +If you want to use the serial interface: |
| 157 | + |
| 158 | +> pip install -U pymodbus\[serial\] |
| 159 | +
|
| 160 | +This will install pymodbus, r |
| 161 | + |
| 162 | +To install pymodbus with options run: |
| 163 | + |
| 164 | +> pip install -U pymodbus\[\<option\>,\...\] |
| 165 | +
|
| 166 | +Available options are: |
| 167 | + |
| 168 | +- **repl**, install dependencies needed by pymodbus.repl |
| 169 | +- **serial**, installs serial drivers. |
| 170 | +- **simulator**, install dependencies needed by pymodbus.simulator |
| 171 | +- **documentation**, installs tools to generate documentation. |
| 172 | +- **development**, installs development tools needed to enable |
| 173 | + test/check of pymodbus changes. |
| 174 | +- **all**, installs all of the above |
| 175 | + |
| 176 | +## Installing with github |
| 177 | + |
| 178 | +Before cloning the repo, you need to install python3 (preferable 3.11) |
| 179 | +and make and activate a virtual environment: |
| 180 | + |
| 181 | + python3 -m venv /path/to/new/virtual/environment |
| 182 | + |
| 183 | + source .venv/bin/activate |
| 184 | + |
| 185 | +Clone the source and install from there: |
| 186 | + |
| 187 | + git clone git://github.com/pymodbus-dev/pymodbus.git |
| 188 | + cd pymodbus |
| 189 | + |
| 190 | +To get a specific release: |
| 191 | + |
| 192 | + git checkout v3.5.2 |
| 193 | + |
| 194 | +To get bleeding edge: |
| 195 | + |
| 196 | + git checkout dev |
| 197 | + |
| 198 | +Install required development tools: |
| 199 | + |
| 200 | + pip install -e ".[development]" |
| 201 | + |
| 202 | + pre-commit install |
| 203 | + |
| 204 | +This installs pymodbus in your virtual environment with pointers |
| 205 | +directly to the pymodbus directory, so any change you make is |
| 206 | +immediately available as if installed. It will also install |
| 207 | +[pre-commit]{.title-ref} git hooks. |
| 208 | + |
| 209 | +The repository contains a number of important branches and tags. |
| 210 | + |
| 211 | +: - **dev** is where all development happens, this branch is not |
| 212 | + always stable. |
| 213 | + - **master** is where are releases are kept. |
| 214 | + - All releases are tagged with **vX.Y.Z** (e.g. v2.5.3) |
| 215 | + |
| 216 | +If a maintenance release of an old version is needed (e.g. v2.5.4), the |
| 217 | +release tag is used to create a branch with the same name, and |
| 218 | +maintenance development is merged here. |
| 219 | + |
| 220 | +## Current Work In Progress |
| 221 | + |
| 222 | +The maintenance team is very small with limited capacity and few modbus |
| 223 | +devices. |
| 224 | + |
| 225 | +If your company would like your device tested or have a cloud based |
| 226 | +device simulation, feel free to contact us. We are happy to help your |
| 227 | +company solve your modbus challenges. |
| 228 | + |
| 229 | +That said, the current work mainly involves polishing the library and |
| 230 | +solving issues: |
| 231 | + |
| 232 | +> - Fixing bugs/feature requests |
| 233 | +> - Architecture documentation |
| 234 | +> - Functional testing against any reference we can find |
| 235 | +> - The remaining edges of the protocol (that we think no one uses) |
| 236 | +
|
| 237 | +There are 2 bigger projects ongoing: |
| 238 | + |
| 239 | +> - rewriting the internal part of all clients (both sync and async) |
| 240 | +> - Make the simulator datastore THE datastore |
| 241 | +
|
| 242 | +## Development Instructions |
| 243 | + |
| 244 | +The current code base is compatible python \>= 3.8. Here are some of the |
| 245 | +common commands to perform a range of activities |
| 246 | + |
| 247 | +> ./check_ci.sh run the same checks as CI runs on a pull request. |
| 248 | +
|
| 249 | +## Generate documentation |
| 250 | + |
| 251 | +**Remark** Assumes that you have installed documentation tools: |
| 252 | + |
| 253 | +> pip install -e \".\[documentation\]\" |
| 254 | +
|
| 255 | +to build do: |
| 256 | + |
| 257 | +> cd doc ./build_html |
| 258 | +
|
| 259 | +The documentation is available in \<root\>/build/html/html |
| 260 | + |
| 261 | +## Contributing |
| 262 | + |
| 263 | +Just fork the repo and raise your PR against [dev]{.title-ref} branch. |
| 264 | + |
| 265 | +We always have more work than time, so feel free to open a discussion / |
| 266 | +issue on a theme you want to solve. |
| 267 | + |
| 268 | +## License Information |
| 269 | + |
| 270 | +Released under the [BSD License](LICENSE) |
0 commit comments