python-snap7 3.4.0__tar.gz → 3.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. {python_snap7-3.4.0 → python_snap7-3.5.0}/CHANGES.md +17 -0
  2. {python_snap7-3.4.0/python_snap7.egg-info → python_snap7-3.5.0}/PKG-INFO +2 -2
  3. python_snap7-3.5.0/doc/API/async-client.rst +53 -0
  4. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/client.rst +2 -9
  5. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/connecting.rst +4 -3
  6. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/index.rst +1 -0
  7. python_snap7-3.5.0/doc/multi-variable.rst +97 -0
  8. python_snap7-3.5.0/doc/thread-safety.rst +100 -0
  9. python_snap7-3.5.0/example/boolean.py +52 -0
  10. {python_snap7-3.4.0 → python_snap7-3.5.0}/example/example.py +14 -13
  11. python_snap7-3.5.0/example/logo_7_8.py +59 -0
  12. python_snap7-3.5.0/example/read_multi.py +40 -0
  13. python_snap7-3.5.0/example/s7_symbols.py +42 -0
  14. python_snap7-3.5.0/example/write_multi.py +50 -0
  15. {python_snap7-3.4.0 → python_snap7-3.5.0}/pyproject.toml +2 -2
  16. {python_snap7-3.4.0 → python_snap7-3.5.0/python_snap7.egg-info}/PKG-INFO +2 -2
  17. {python_snap7-3.4.0 → python_snap7-3.5.0}/python_snap7.egg-info/SOURCES.txt +1 -0
  18. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/async_client.py +16 -9
  19. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/client.py +40 -19
  20. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/optimizer.py +16 -3
  21. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/s7protocol.py +17 -11
  22. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/server/__init__.py +14 -4
  23. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/szl.py +36 -0
  24. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_async_client.py +7 -3
  25. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_async_typed_access.py +8 -0
  26. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_client.py +19 -4
  27. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_optimizer.py +43 -0
  28. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_server.py +72 -5
  29. {python_snap7-3.4.0 → python_snap7-3.5.0}/tox.ini +0 -2
  30. python_snap7-3.4.0/doc/multi-variable.rst +0 -51
  31. python_snap7-3.4.0/doc/thread-safety.rst +0 -39
  32. python_snap7-3.4.0/example/boolean.py +0 -46
  33. python_snap7-3.4.0/example/logo_7_8.py +0 -53
  34. python_snap7-3.4.0/example/read_multi.py +0 -68
  35. python_snap7-3.4.0/example/s7_symbols.py +0 -38
  36. python_snap7-3.4.0/example/write_multi.py +0 -52
  37. {python_snap7-3.4.0 → python_snap7-3.5.0}/LICENSE +0 -0
  38. {python_snap7-3.4.0 → python_snap7-3.5.0}/MANIFEST.in +0 -0
  39. {python_snap7-3.4.0 → python_snap7-3.5.0}/README.rst +0 -0
  40. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/client-base.rst +0 -0
  41. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/connection.rst +0 -0
  42. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/datatypes.rst +0 -0
  43. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/demo.rst +0 -0
  44. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/discovery.rst +0 -0
  45. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/error.rst +0 -0
  46. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/log.rst +0 -0
  47. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/logo.rst +0 -0
  48. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/optimizer.rst +0 -0
  49. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/partner.rst +0 -0
  50. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/ppi.rst +0 -0
  51. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/rate-limiter.rst +0 -0
  52. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/s7protocol.rst +0 -0
  53. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/server.rst +0 -0
  54. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/szl.rst +0 -0
  55. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/tags.rst +0 -0
  56. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/type.rst +0 -0
  57. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/API/util.rst +0 -0
  58. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/Makefile +0 -0
  59. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/_static/.phony +0 -0
  60. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/advanced.rst +0 -0
  61. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/cli.rst +0 -0
  62. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/conf.py +0 -0
  63. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/connection-issues.rst +0 -0
  64. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/development.rst +0 -0
  65. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/error-reference.rst +0 -0
  66. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/installation.rst +0 -0
  67. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/introduction.rst +0 -0
  68. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/limitations.rst +0 -0
  69. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/plc-support.rst +0 -0
  70. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/ppi.rst +0 -0
  71. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/reading-writing.rst +0 -0
  72. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/real-plc-testing.rst +0 -0
  73. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/server.rst +0 -0
  74. {python_snap7-3.4.0 → python_snap7-3.5.0}/doc/tia-portal-config.rst +0 -0
  75. {python_snap7-3.4.0 → python_snap7-3.5.0}/example/db1_layout.txt +0 -0
  76. {python_snap7-3.4.0 → python_snap7-3.5.0}/example/db_layouts.py +0 -0
  77. {python_snap7-3.4.0 → python_snap7-3.5.0}/example/ppi.py +0 -0
  78. {python_snap7-3.4.0 → python_snap7-3.5.0}/example/prometheus_metrics.py +0 -0
  79. {python_snap7-3.4.0 → python_snap7-3.5.0}/python_snap7.egg-info/dependency_links.txt +0 -0
  80. {python_snap7-3.4.0 → python_snap7-3.5.0}/python_snap7.egg-info/entry_points.txt +0 -0
  81. {python_snap7-3.4.0 → python_snap7-3.5.0}/python_snap7.egg-info/requires.txt +0 -0
  82. {python_snap7-3.4.0 → python_snap7-3.5.0}/python_snap7.egg-info/top_level.txt +0 -0
  83. {python_snap7-3.4.0 → python_snap7-3.5.0}/s7/__init__.py +0 -0
  84. {python_snap7-3.4.0 → python_snap7-3.5.0}/setup.cfg +0 -0
  85. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/__init__.py +0 -0
  86. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/cli.py +0 -0
  87. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/client_base.py +0 -0
  88. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/connection.py +0 -0
  89. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/datatypes.py +0 -0
  90. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/demo.py +0 -0
  91. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/discovery.py +0 -0
  92. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/error.py +0 -0
  93. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/log.py +0 -0
  94. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/logo.py +0 -0
  95. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/partner.py +0 -0
  96. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/ppi.py +0 -0
  97. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/py.typed +0 -0
  98. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/rate_limiter.py +0 -0
  99. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/server/__main__.py +0 -0
  100. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/tags.py +0 -0
  101. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/type.py +0 -0
  102. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/util/__init__.py +0 -0
  103. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/util/db.py +0 -0
  104. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/util/getters.py +0 -0
  105. {python_snap7-3.4.0 → python_snap7-3.5.0}/snap7/util/setters.py +0 -0
  106. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/__init__.py +0 -0
  107. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/conftest.py +0 -0
  108. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/features/real_plc/connection.feature +0 -0
  109. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/features/real_plc/lifecycle.feature +0 -0
  110. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/features/real_plc/read.feature +0 -0
  111. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/features/real_plc/report.schema.json +0 -0
  112. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/features/real_plc/write.feature +0 -0
  113. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/plc_setup/e2e_test_dbs.scl +0 -0
  114. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/real_plc/__init__.py +0 -0
  115. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/real_plc/reporting.py +0 -0
  116. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/real_plc/support.py +0 -0
  117. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/real_plc/test_acceptance.py +0 -0
  118. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_api_surface.py +0 -0
  119. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_behavioral_compatibility.py +0 -0
  120. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_cli.py +0 -0
  121. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_client_e2e.py +0 -0
  122. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_conformance.py +0 -0
  123. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_connection.py +0 -0
  124. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_coverage_gaps.py +0 -0
  125. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_datatypes.py +0 -0
  126. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_demo.py +0 -0
  127. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_discovery.py +0 -0
  128. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_error.py +0 -0
  129. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_finalize.py +0 -0
  130. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_hypothesis.py +0 -0
  131. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_lean_regressions.py +0 -0
  132. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_logging.py +0 -0
  133. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_logo_client.py +0 -0
  134. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_logo_reconnect_options.py +0 -0
  135. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_mainloop.py +0 -0
  136. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_multipacket.py +0 -0
  137. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_operation_hook.py +0 -0
  138. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_partner.py +0 -0
  139. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_ppi.py +0 -0
  140. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_property.py +0 -0
  141. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_rate_limiter.py +0 -0
  142. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_real_plc_support.py +0 -0
  143. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_reconnect.py +0 -0
  144. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_routing.py +0 -0
  145. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_s7protocol.py +0 -0
  146. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_server_cli.py +0 -0
  147. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_stress.py +0 -0
  148. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_tags.py +0 -0
  149. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_typed_access.py +0 -0
  150. {python_snap7-3.4.0 → python_snap7-3.5.0}/tests/test_util.py +0 -0
@@ -1,6 +1,23 @@
1
1
  CHANGES
2
2
  ========
3
3
 
4
+ 3.5.0
5
+ -----
6
+
7
+ ### Bug fixes
8
+
9
+ * `get_cpu_state()` now reads the CPU's operating state from SZL 0x0424, in both clients. Previously it sent a read
10
+ request with no address and returned `"S7CpuStatusRun"` whatever the PLC answered. Startup, HOLD and DEFECT are
11
+ reported as `"S7CpuStatusStop"`, as native Snap7 does. A PLC that refuses SZL 0x0424 now raises `S7ProtocolError`;
12
+ the heartbeat of the synchronous client counts such a refusal as a live connection. Not yet tested on hardware (#988).
13
+ * The server answers SZL 0x0424 from its CPU state, and refuses a read request that has no address specification.
14
+ Previously it answered such a request with the first four bytes of DB1 (#988).
15
+ * `read_tags` and `read_multi_vars` with a list of dicts now accept more than 20 items, in both clients. Previously
16
+ they raised `ValueError` over `MAX_VARS`, although the read optimizer already splits a read over several requests.
17
+ The optimizer now also puts at most 20 items in one request; `optimizer.packetize` takes a `max_items` argument
18
+ for this. The ctypes form of `read_multi_vars` and `write_multi_vars` keep the limit (#989).
19
+ * `read_tags` now raises `NotImplementedError` for a symbolic tag, as `read_tag` does, in both clients (#989).
20
+
4
21
  3.4.0
5
22
  -----
6
23
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: python-snap7
3
- Version: 3.4.0
3
+ Version: 3.5.0
4
4
  Summary: Pure Python S7 communication library for Siemens PLCs
5
5
  Author-email: Gijs Molenaar <gijsmolenaar@gmail.com>
6
6
  License-Expression: MIT
@@ -12,7 +12,7 @@ Classifier: Environment :: Console
12
12
  Classifier: Topic :: System :: Hardware
13
13
  Classifier: Intended Audience :: Developers
14
14
  Classifier: Intended Audience :: Manufacturing
15
- Classifier: Operating System :: POSIX
15
+ Classifier: Operating System :: OS Independent
16
16
  Classifier: Programming Language :: Python :: 3.10
17
17
  Classifier: Programming Language :: Python :: 3.11
18
18
  Classifier: Programming Language :: Python :: 3.12
@@ -0,0 +1,53 @@
1
+ Async Client
2
+ ============
3
+
4
+ ``AsyncClient`` is the ``asyncio`` counterpart of :doc:`client`. It has the
5
+ same PLC operations, and every method that talks to the PLC is a coroutine::
6
+
7
+ import asyncio
8
+ from s7 import AsyncClient
9
+
10
+ async def main() -> None:
11
+ async with AsyncClient() as client:
12
+ await client.connect("192.168.1.10", 0, 1)
13
+ data = await client.db_read(1, 0, 4)
14
+ await client.db_write(1, 0, bytearray([1, 2, 3, 4]))
15
+
16
+ asyncio.run(main())
17
+
18
+ Leaving the ``async with`` block disconnects the client.
19
+
20
+ Concurrency
21
+ -----------
22
+
23
+ An internal ``asyncio.Lock`` serialises each request and its reply, so several
24
+ coroutines can share one client::
25
+
26
+ async def read_all(client: AsyncClient) -> list[bytearray]:
27
+ return await asyncio.gather(
28
+ client.db_read(1, 0, 4),
29
+ client.db_read(1, 10, 4),
30
+ client.db_read(2, 0, 8),
31
+ )
32
+
33
+ The requests still go to the PLC one after the other; ``gather`` only lets the
34
+ rest of the application run while they wait. One client belongs to one event
35
+ loop. Do not call it from other threads.
36
+
37
+ Differences from ``Client``
38
+ ---------------------------
39
+
40
+ * There is no heartbeat thread and no ``heartbeat_interval`` argument.
41
+ ``is_alive`` reports the connection state seen by the last operation.
42
+ * ``read_multi_vars`` and ``write_multi_vars`` accept only the dict form, and
43
+ ``read_multi_vars`` and ``read_tags`` read the items one after the other.
44
+ There is no read optimizer and no ``max_parallel``. See
45
+ :doc:`../multi-variable`.
46
+
47
+ s7.AsyncClient
48
+ --------------
49
+
50
+ .. automodule:: snap7.async_client
51
+ :members:
52
+ :inherited-members:
53
+ :exclude-members: AsyncISOTCPConnection
@@ -27,7 +27,8 @@ Use ``AsyncClient`` when the surrounding application uses ``asyncio``::
27
27
  Both clients expose the same main PLC operations, including area and DB
28
28
  access, block transfer, CPU information and control, clock access, force
29
29
  operations, and session passwords. Methods that perform I/O are coroutines on
30
- ``AsyncClient``. See :doc:`../advanced` for the less common operations.
30
+ ``AsyncClient``, which is documented in :doc:`async-client`. See
31
+ :doc:`../advanced` for the less common operations.
31
32
 
32
33
  s7.Client
33
34
  ---------
@@ -35,11 +36,3 @@ s7.Client
35
36
  .. automodule:: snap7.client
36
37
  :members:
37
38
  :inherited-members:
38
-
39
- s7.AsyncClient
40
- --------------
41
-
42
- .. automodule:: snap7.async_client
43
- :members:
44
- :inherited-members:
45
- :exclude-members: AsyncISOTCPConnection
@@ -153,11 +153,12 @@ When the target PLC sits on a different subnet behind a gateway PLC, use
153
153
  data = client.db_read(1, 0, 4)
154
154
  client.disconnect()
155
155
 
156
- Legacy ``snap7`` Package
156
+ The ``snap7`` import name
157
157
  -------------------------
158
158
 
159
- If you have existing code using ``snap7.Client``, it continues to work
160
- unchanged — ``snap7`` is an alias for ``s7``:
159
+ Existing code that uses ``snap7.Client`` continues to work unchanged. The
160
+ implementation lives in the ``snap7`` package and ``s7`` re-exports it, so
161
+ both names give you the same classes:
161
162
 
162
163
  .. code-block:: python
163
164
 
@@ -43,6 +43,7 @@ Welcome to python-snap7's documentation!
43
43
  :caption: API Reference
44
44
 
45
45
  API/client
46
+ API/async-client
46
47
  API/server
47
48
  API/partner
48
49
  API/logo
@@ -0,0 +1,97 @@
1
+ Multi-Variable Read and Write
2
+ =============================
3
+
4
+ Reading several variables in one call is faster than reading them one by one:
5
+ the client merges adjacent addresses and packs the rest into as few PDU
6
+ exchanges as the negotiated PDU size allows.
7
+
8
+ Reading tags
9
+ ------------
10
+
11
+ ``read_tags`` takes address strings (or :class:`~snap7.tags.Tag` objects) and
12
+ returns the decoded values in the same order:
13
+
14
+ .. code-block:: python
15
+
16
+ from s7 import Client
17
+
18
+ client = Client()
19
+ client.connect("192.168.1.10", 0, 1)
20
+
21
+ level, setpoint, count = client.read_tags(
22
+ ["DB200.DBD16:REAL", "DB200.DBD12:REAL", "DB200.DBW2:INT"]
23
+ )
24
+
25
+ See :doc:`API/tags` for the address syntax.
26
+
27
+ Reading raw bytes
28
+ -----------------
29
+
30
+ ``read_multi_vars`` takes a list of dicts with ``area``, ``start``, ``size``
31
+ and, for data blocks, ``db_number``. It returns a result code and one
32
+ ``bytearray`` per item, in the order of the request:
33
+
34
+ .. code-block:: python
35
+
36
+ from s7.type import Area
37
+ from s7.util import get_int, get_real
38
+
39
+ items = [
40
+ {"area": Area.DB, "db_number": 200, "start": 16, "size": 4},
41
+ {"area": Area.DB, "db_number": 200, "start": 2, "size": 2},
42
+ {"area": Area.MK, "start": 20, "size": 1},
43
+ ]
44
+ _, buffers = client.read_multi_vars(items)
45
+
46
+ level = get_real(buffers[0], 0)
47
+ count = get_int(buffers[1], 0)
48
+
49
+ A failed read raises an exception from :mod:`snap7.error`; there is no
50
+ per-item status to check.
51
+
52
+ Writing
53
+ -------
54
+
55
+ ``write_multi_vars`` takes the same dicts with ``data`` instead of ``size``:
56
+
57
+ .. code-block:: python
58
+
59
+ client.write_multi_vars(
60
+ [
61
+ {"area": Area.DB, "db_number": 1, "start": 0, "data": bytearray([0, 10, 0, 20])},
62
+ {"area": Area.MK, "start": 20, "data": bytearray([0x01])},
63
+ ]
64
+ )
65
+
66
+ The items are written one after the other, each in its own request. The call
67
+ raises on the first item the PLC refuses, and the items before it stay
68
+ written.
69
+
70
+ Limits and tuning
71
+ -----------------
72
+
73
+ .. warning::
74
+
75
+ One call accepts at most **20 items** (``Client.MAX_VARS``) and raises
76
+ ``ValueError`` above that. Split longer lists across several calls.
77
+
78
+ * The read optimizer is experimental. Set ``client.use_optimizer = False`` to
79
+ read each item with its own request instead. See :doc:`API/optimizer`.
80
+ * When a read needs more than one PDU, ``Client`` sends up to
81
+ ``client.max_parallel`` requests before it reads the replies. See
82
+ :doc:`thread-safety`.
83
+ * ``AsyncClient`` has the same methods as coroutines, but reads the items one
84
+ after the other without the optimizer.
85
+
86
+ The ``S7DataItem`` form
87
+ -----------------------
88
+
89
+ ``Client.read_multi_vars`` and ``Client.write_multi_vars`` still accept the
90
+ ctypes ``S7DataItem`` structures of the original Snap7 library, so that old
91
+ code keeps working. This path reads and writes the items one at a time and
92
+ never sets the ``Result`` field of an item; errors raise exceptions instead.
93
+ ``AsyncClient`` does not accept it. Use ``read_tags`` or the dict form in new
94
+ code.
95
+
96
+ Complete scripts are in ``example/read_multi.py`` and
97
+ ``example/write_multi.py``.
@@ -0,0 +1,100 @@
1
+ Thread Safety
2
+ =============
3
+
4
+ The ``Client`` class is **not** thread-safe. Concurrent calls from multiple
5
+ threads on the same ``Client`` instance will corrupt the TCP connection state
6
+ and cause unpredictable errors.
7
+
8
+ **Option 1: One client per thread**
9
+
10
+ .. code-block:: python
11
+
12
+ import threading
13
+ from s7 import Client
14
+
15
+ def worker(address: str, rack: int, slot: int) -> None:
16
+ client = Client()
17
+ client.connect(address, rack, slot)
18
+ data = client.db_read(1, 0, 10)
19
+ client.disconnect()
20
+
21
+ t1 = threading.Thread(target=worker, args=("192.168.1.10", 0, 1))
22
+ t2 = threading.Thread(target=worker, args=("192.168.1.10", 0, 1))
23
+ t1.start()
24
+ t2.start()
25
+
26
+ **Option 2: Shared client with a lock**
27
+
28
+ .. code-block:: python
29
+
30
+ import threading
31
+ from s7 import Client
32
+
33
+ client = Client()
34
+ client.connect("192.168.1.10", 0, 1)
35
+ lock = threading.Lock()
36
+
37
+ def safe_read(db: int, start: int, size: int) -> bytearray:
38
+ with lock:
39
+ return client.db_read(db, start, size)
40
+
41
+ The heartbeat thread
42
+ --------------------
43
+
44
+ ``Client(heartbeat_interval=10)`` starts a daemon thread named
45
+ ``s7-heartbeat`` when the client connects. Every interval it reads the CPU
46
+ state to check that the PLC still answers, and ``client.is_alive`` reports the
47
+ result of the last probe. ``disconnect()`` stops the thread. With the default
48
+ ``heartbeat_interval=0`` no thread is started.
49
+
50
+ The client holds an internal lock around each request and its reply, so a
51
+ probe never lands in the middle of one of your requests. This lock exists for
52
+ the heartbeat. It covers a single exchange, not a whole operation: a large
53
+ read, an upload or a download takes several exchanges. It does not make a
54
+ shared ``Client`` safe to call from several threads, so the two options above
55
+ still apply.
56
+
57
+ Two things follow from the probe running on its own thread:
58
+
59
+ * With ``auto_reconnect=True`` the heartbeat thread reconnects when a probe
60
+ fails, so the ``on_disconnect`` and ``on_reconnect`` callbacks can run on
61
+ the heartbeat thread. Keep them short and do not touch state that your main
62
+ thread uses without a lock of your own.
63
+ * A probe is a request like any other. It counts against
64
+ ``max_requests_per_second``, and your next call waits while one is in
65
+ flight.
66
+
67
+ ``AsyncClient`` has no heartbeat thread. See :doc:`API/async-client`.
68
+
69
+ Parallel requests on one connection: ``max_parallel``
70
+ -----------------------------------------------------
71
+
72
+ ``max_parallel`` is not a thread count. When ``read_multi_vars`` or
73
+ ``read_tags`` needs more than one PDU, the client sends up to
74
+ ``client.max_parallel`` requests on its single connection before it reads the
75
+ replies, and matches each reply to its request by sequence number. All of this
76
+ happens in the calling thread.
77
+
78
+ ``connect()`` sets the value from the negotiated PDU size:
79
+
80
+ ================== ================
81
+ PDU size (bytes) ``max_parallel``
82
+ ================== ================
83
+ 960 or more 8
84
+ 480 to 959 4
85
+ 240 to 479 2
86
+ below 240 1
87
+ ================== ================
88
+
89
+ A PLC accepts only a limited number of requests in flight. If multi-variable
90
+ reads time out or the PLC drops the connection, send them one at a time:
91
+
92
+ .. code-block:: python
93
+
94
+ client.connect("192.168.1.10", 0, 1)
95
+ client.max_parallel = 1
96
+
97
+ Set it after ``connect()``, because connecting (but not an automatic
98
+ reconnect) sets it again. The value is left alone when
99
+ ``client.use_optimizer`` is ``False``, and it only affects multi-variable
100
+ reads; every other operation sends one request and waits for its reply.
@@ -0,0 +1,52 @@
1
+ """
2
+ So how to change a bool value?
3
+
4
+ 1) Read out the _bytearray your boolean values are in.
5
+ 2) In this byte_array you need to find the byte (byteindex)
6
+ 3) Find the bit in this byte (bitindex) so you can
7
+ 4) set the correct value with utility function set_bool which does all the hard work.
8
+ set_bool(_bytearray = data which you read out before.., byte_index, bool_index, value),
9
+ 5) write back the changed bytearray back to the PLC.
10
+
11
+ A round trip wil take 5ms.
12
+
13
+ The example code
14
+
15
+ https://github.com/gijzelaerr/python-snap7/blob/master/example/
16
+
17
+ the minimun amount of data being read or written to a plc is 1 byte.
18
+ """
19
+
20
+ from s7 import Client
21
+ from s7.type import Area
22
+ from s7.util import set_bool, set_int
23
+
24
+
25
+ def main() -> None:
26
+ plc = Client()
27
+ plc.connect("192.168.200.24", 0, 3)
28
+
29
+ # In this example boolean in DB 31 at byte 120 and bit 5 is changed. = 120.5
30
+
31
+ reading = plc.db_read(31, 120, 1) # read 1 byte from db 31 staring from byte 120
32
+ set_bool(reading, 0, 5, True) # set a value of fifth bit
33
+ plc.db_write(31, 120, reading) # write back the bytearray and now the boolean value is changed in the PLC.
34
+
35
+ # NOTE you could also use the read_area and write_area functions.
36
+ # then you can specify an area to read from:
37
+ # https://github.com/gijzelaerr/python-snap7/blob/master/snap7/type.py
38
+
39
+ # play with these functions.
40
+ plc.read_area(area=Area.MK, db_number=0, start=20, size=2)
41
+
42
+ data = bytearray(2) # an INT is two bytes
43
+ set_int(data, 0, 127)
44
+ plc.write_area(area=Area.MK, db_number=0, start=20, data=data)
45
+ # read the client source code!
46
+ # and official snap7 documentation
47
+
48
+ plc.disconnect()
49
+
50
+
51
+ if __name__ == "__main__":
52
+ main()
@@ -8,12 +8,11 @@ import time
8
8
  from db_layouts import rc_if_db_1_layout
9
9
  from db_layouts import tank_rc_if_db_layout
10
10
 
11
- from snap7 import Client, Row, DB
12
- from snap7.type import Area
13
- from util.db import print_row
11
+ from s7 import Client, Row, DB
12
+ from s7.type import Area
13
+ from s7.util.db import print_row
14
14
 
15
15
  client = Client()
16
- client.connect("192.168.200.24", 0, 3)
17
16
 
18
17
 
19
18
  def get_db1() -> None:
@@ -190,12 +189,14 @@ def print_open() -> None:
190
189
  print(row)
191
190
 
192
191
 
193
- # read_tank_db()
194
- # open_and_close()
195
- # open_and_close_db1()
196
- # time.sleep(1)
197
- # show_row(2)
198
- print_tag()
199
- # print_open()
200
-
201
- client.disconnect()
192
+ if __name__ == "__main__":
193
+ client.connect("192.168.200.24", 0, 3)
194
+ try:
195
+ # read_tank_db()
196
+ # open_and_close()
197
+ # open_and_close_db1()
198
+ # show_row(2)
199
+ print_tag()
200
+ # print_open()
201
+ finally:
202
+ client.disconnect()
@@ -0,0 +1,59 @@
1
+ import logging
2
+
3
+ from snap7.logo import Logo
4
+
5
+ # for setup the Logo connection please follow this link
6
+ # https://snap7.sourceforge.net/logo.html
7
+
8
+
9
+ logging.basicConfig(level=logging.INFO)
10
+
11
+ # Siemens LOGO devices Logo 8 is the default
12
+ Logo_7 = True
13
+
14
+ logger = logging.getLogger(__name__)
15
+
16
+
17
+ def main() -> None:
18
+ plc = Logo()
19
+ plc.connect("192.168.0.41", 0x1000, 0x2000)
20
+
21
+ if plc.get_connected():
22
+ logger.info("connected")
23
+
24
+ # read I1 from logo
25
+ vm_address = "V923.0" if Logo_7 else "V1024.0"
26
+ print(f"I1: {str(plc.read(vm_address))}")
27
+
28
+ # write some values in VM addresses between 0 and 100
29
+
30
+ value_1 = 0b10110001
31
+ value_2 = 480
32
+
33
+ print("write 0b10110001 to V10")
34
+ plc.write("V10", value_1)
35
+
36
+ print(f"read V10.0 must be 1 - check: {str(plc.read('V10.0'))}")
37
+ print(f"read V10.3 must be 0 - check: {str(plc.read('V10.3'))}")
38
+ print(f"read V10.7 must be 1 - check: {str(plc.read('V10.7'))}")
39
+
40
+ print("write 480 analog value to VW20")
41
+ plc.write("VW20", value_2)
42
+
43
+ print(f"read VW20 must be 480 - check: {str(plc.read('VW20'))}")
44
+
45
+ print("trigger V10.2")
46
+ plc.write("V10.2", 0)
47
+ plc.write("V10.2", 1)
48
+ plc.write("V10.2", 0)
49
+
50
+ else:
51
+ logger.error("Connection failed")
52
+
53
+ plc.disconnect()
54
+ logger.info("Disconnected")
55
+ plc.destroy()
56
+
57
+
58
+ if __name__ == "__main__":
59
+ main()
@@ -0,0 +1,40 @@
1
+ """
2
+ Read several variables in one call.
3
+
4
+ ``read_tags`` takes address strings and returns decoded values. ``read_multi_vars``
5
+ takes a list of dicts and returns the raw bytes, for when you decode them yourself.
6
+ Both batch the reads into as few PDU exchanges as the PLC allows.
7
+
8
+ Usage:
9
+ python example/read_multi.py 192.168.1.10
10
+ """
11
+
12
+ import sys
13
+
14
+ from s7 import Client
15
+ from s7.type import Area
16
+ from s7.util import get_int, get_real
17
+
18
+
19
+ def main(address: str) -> None:
20
+ client = Client()
21
+ client.connect(address, 0, 1)
22
+ try:
23
+ # Decoded values, in the order of the request.
24
+ level, setpoint, count = client.read_tags(["DB200.DBD16:REAL", "DB200.DBD12:REAL", "DB200.DBW2:INT"])
25
+ print(f"level={level!r} setpoint={setpoint!r} count={count!r}")
26
+
27
+ # Raw bytes: one bytearray per item, in the order of the request.
28
+ items = [
29
+ {"area": Area.DB, "db_number": 200, "start": 16, "size": 4}, # REAL
30
+ {"area": Area.DB, "db_number": 200, "start": 12, "size": 4}, # REAL
31
+ {"area": Area.DB, "db_number": 200, "start": 2, "size": 2}, # INT
32
+ ]
33
+ _, buffers = client.read_multi_vars(items)
34
+ print([get_real(buffers[0], 0), get_real(buffers[1], 0), get_int(buffers[2], 0)])
35
+ finally:
36
+ client.disconnect()
37
+
38
+
39
+ if __name__ == "__main__":
40
+ main(sys.argv[1] if len(sys.argv) > 1 else "192.168.1.10")
@@ -0,0 +1,42 @@
1
+ """Tag-based symbolic addressing example (s7 legacy client).
2
+
3
+ Usage:
4
+ python example/s7_symbols.py 192.168.1.10
5
+ """
6
+
7
+ import sys
8
+
9
+ from s7 import Client
10
+ from s7.tags import Tag
11
+
12
+
13
+ def main(address: str) -> None:
14
+ client = Client()
15
+ client.connect(address, 0, 1)
16
+
17
+ # Ad-hoc tag read using PLC4X-style syntax
18
+ speed = client.read_tag("DB1.DBD0:REAL")
19
+ running = client.read_tag("DB1.DBX4.0:BOOL")
20
+ print(f"Speed: {speed!r}, Running: {running!r}")
21
+
22
+ # Write a value
23
+ client.write_tag("DB1.DBW6:INT", 1500)
24
+
25
+ # Read multiple tags in one optimized request
26
+ values = client.read_tags(["DB1.DBD0:REAL", "DB1.DBW6:INT"])
27
+ print(f"Batch: {values!r}")
28
+
29
+ # Or build tags programmatically / load from file
30
+ # tags = load_csv("tags.csv") # returns dict[str, Tag]
31
+ # value = client.read_tag(tags["Motor.Speed"])
32
+
33
+ # Tag instances are also accepted directly
34
+ temperature_tag = Tag.from_string("DB1.DBD0:REAL", name="Temperature")
35
+ temp = client.read_tag(temperature_tag)
36
+ print(f"Temperature: {temp!r}")
37
+
38
+ client.disconnect()
39
+
40
+
41
+ if __name__ == "__main__":
42
+ main(sys.argv[1] if len(sys.argv) > 1 else "192.168.1.10")
@@ -0,0 +1,50 @@
1
+ """
2
+ Write several variables in one call.
3
+
4
+ ``write_multi_vars`` takes a list of dicts, each with the bytes to write. The items
5
+ are written one after the other and the call raises on the first one the PLC refuses,
6
+ so earlier items stay written. Use ``write_tag`` to write a single typed value.
7
+
8
+ Usage:
9
+ python example/write_multi.py 192.168.1.10
10
+ """
11
+
12
+ import sys
13
+
14
+ from s7 import Client
15
+ from s7.type import Area
16
+ from s7.util import set_int, set_real
17
+
18
+
19
+ def main(address: str) -> None:
20
+ client = Client()
21
+ client.connect(address, 0, 1)
22
+ try:
23
+ int_values = [10, 20, 30, 40]
24
+ ints = bytearray(2 * len(int_values))
25
+ for i, value in enumerate(int_values):
26
+ set_int(ints, 2 * i, value)
27
+
28
+ real = bytearray(4)
29
+ set_real(real, 0, 42.5)
30
+
31
+ client.write_multi_vars(
32
+ [
33
+ {"area": Area.DB, "db_number": 1, "start": 0, "data": ints},
34
+ {"area": Area.DB, "db_number": 1, "start": 8, "data": real},
35
+ {"area": Area.MK, "start": 20, "data": bytearray([0x01])},
36
+ ]
37
+ )
38
+
39
+ # A single typed value by address.
40
+ client.write_tag("DB1.DBW12:INT", 1500)
41
+
42
+ # Read everything back.
43
+ tags = [f"DB1.DBW{2 * i}:INT" for i in range(len(int_values))] + ["DB1.DBD8:REAL", "DB1.DBW12:INT", "MB20:BYTE"]
44
+ print(dict(zip(tags, client.read_tags(tags))))
45
+ finally:
46
+ client.disconnect()
47
+
48
+
49
+ if __name__ == "__main__":
50
+ main(sys.argv[1] if len(sys.argv) > 1 else "192.168.1.10")
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "python-snap7"
7
- version = "3.4.0"
7
+ version = "3.5.0"
8
8
  description = "Pure Python S7 communication library for Siemens PLCs"
9
9
  readme = "README.rst"
10
10
  authors = [
@@ -16,7 +16,7 @@ classifiers = [
16
16
  "Topic :: System :: Hardware",
17
17
  "Intended Audience :: Developers",
18
18
  "Intended Audience :: Manufacturing",
19
- "Operating System :: POSIX",
19
+ "Operating System :: OS Independent",
20
20
  "Programming Language :: Python :: 3.10",
21
21
  "Programming Language :: Python :: 3.11",
22
22
  "Programming Language :: Python :: 3.12",
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: python-snap7
3
- Version: 3.4.0
3
+ Version: 3.5.0
4
4
  Summary: Pure Python S7 communication library for Siemens PLCs
5
5
  Author-email: Gijs Molenaar <gijsmolenaar@gmail.com>
6
6
  License-Expression: MIT
@@ -12,7 +12,7 @@ Classifier: Environment :: Console
12
12
  Classifier: Topic :: System :: Hardware
13
13
  Classifier: Intended Audience :: Developers
14
14
  Classifier: Intended Audience :: Manufacturing
15
- Classifier: Operating System :: POSIX
15
+ Classifier: Operating System :: OS Independent
16
16
  Classifier: Programming Language :: Python :: 3.10
17
17
  Classifier: Programming Language :: Python :: 3.11
18
18
  Classifier: Programming Language :: Python :: 3.12
@@ -24,6 +24,7 @@ doc/real-plc-testing.rst
24
24
  doc/server.rst
25
25
  doc/thread-safety.rst
26
26
  doc/tia-portal-config.rst
27
+ doc/API/async-client.rst
27
28
  doc/API/client-base.rst
28
29
  doc/API/client.rst
29
30
  doc/API/connection.rst