PyPlumIO 0.7.6__tar.gz → 0.7.8__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 (156) hide show
  1. {pyplumio-0.7.6 → pyplumio-0.7.8}/PKG-INFO +22 -1
  2. {pyplumio-0.7.6 → pyplumio-0.7.8}/README.md +19 -0
  3. pyplumio-0.7.8/docs/source/cli.rst +161 -0
  4. {pyplumio-0.7.6 → pyplumio-0.7.8}/docs/source/index.rst +1 -0
  5. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/__init__.py +2 -2
  6. pyplumio-0.7.8/pyplumio/__main__.py +10 -0
  7. pyplumio-0.7.8/pyplumio/cli/__init__.py +118 -0
  8. pyplumio-0.7.8/pyplumio/cli/app.py +213 -0
  9. pyplumio-0.7.8/pyplumio/cli/codegen.py +413 -0
  10. pyplumio-0.7.8/pyplumio/cli/model.py +210 -0
  11. pyplumio-0.7.8/pyplumio/cli/session.py +290 -0
  12. pyplumio-0.7.8/pyplumio/cli/state.py +492 -0
  13. pyplumio-0.7.8/pyplumio/cli/ui.py +462 -0
  14. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/connection.py +3 -2
  15. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/data_types.py +1 -1
  16. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/devices/__init__.py +3 -3
  17. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/devices/ecomax.py +1 -1
  18. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/devices/ecoster.py +1 -1
  19. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/devices/mixer.py +1 -1
  20. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/devices/thermostat.py +1 -1
  21. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/filters.py +2 -2
  22. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/frames/__init__.py +2 -2
  23. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/frames/messages.py +1 -1
  24. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/frames/requests.py +2 -2
  25. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/frames/responses.py +2 -2
  26. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/helpers/async_cache.py +1 -1
  27. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/helpers/event_manager.py +2 -2
  28. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/helpers/task_manager.py +1 -1
  29. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/parameters/__init__.py +2 -2
  30. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/parameters/custom/__init__.py +26 -13
  31. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/parameters/ecomax.py +3 -3
  32. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/parameters/mixer.py +2 -2
  33. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/parameters/thermostat.py +2 -2
  34. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/protocol.py +2 -2
  35. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/stream.py +1 -1
  36. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/__init__.py +1 -1
  37. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/alerts.py +1 -1
  38. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/ecomax_parameters.py +1 -1
  39. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/ecomax_service_parameters.py +1 -1
  40. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/frame_versions.py +1 -1
  41. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/mixer_parameters.py +2 -2
  42. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/network_info.py +2 -2
  43. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/product_info.py +1 -1
  44. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/program_version.py +1 -1
  45. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/regulator_data.py +1 -1
  46. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/regulator_data_schema.py +1 -1
  47. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/schedules.py +2 -2
  48. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/sensor_data.py +2 -2
  49. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/structures/thermostat_parameters.py +2 -2
  50. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/utils.py +2 -2
  51. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyproject.toml +12 -7
  52. pyplumio-0.7.8/tests/cli/__init__.py +1 -0
  53. pyplumio-0.7.8/tests/cli/conftest.py +140 -0
  54. pyplumio-0.7.8/tests/cli/test_app.py +519 -0
  55. pyplumio-0.7.8/tests/cli/test_codegen.py +472 -0
  56. pyplumio-0.7.8/tests/cli/test_init.py +241 -0
  57. pyplumio-0.7.8/tests/cli/test_model.py +321 -0
  58. pyplumio-0.7.8/tests/cli/test_session.py +548 -0
  59. pyplumio-0.7.8/tests/cli/test_state.py +840 -0
  60. pyplumio-0.7.8/tests/cli/test_ui.py +937 -0
  61. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/conftest.py +7 -5
  62. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/devices/test_ecomax.py +2 -1
  63. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/devices/test_mixer.py +2 -2
  64. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/parameters/custom/test_init.py +21 -10
  65. pyplumio-0.7.8/tests/test_main.py +20 -0
  66. pyplumio-0.7.6/pyplumio/__main__.py +0 -21
  67. pyplumio-0.7.6/tests/test_main.py +0 -30
  68. {pyplumio-0.7.6 → pyplumio-0.7.8}/.gitignore +0 -0
  69. {pyplumio-0.7.6 → pyplumio-0.7.8}/LICENSE +0 -0
  70. {pyplumio-0.7.6 → pyplumio-0.7.8}/docs/Makefile +0 -0
  71. {pyplumio-0.7.6 → pyplumio-0.7.8}/docs/make.bat +0 -0
  72. {pyplumio-0.7.6 → pyplumio-0.7.8}/docs/source/callbacks.rst +0 -0
  73. {pyplumio-0.7.6 → pyplumio-0.7.8}/docs/source/conf.py +0 -0
  74. {pyplumio-0.7.6 → pyplumio-0.7.8}/docs/source/connecting.rst +0 -0
  75. {pyplumio-0.7.6 → pyplumio-0.7.8}/docs/source/frames.rst +0 -0
  76. {pyplumio-0.7.6 → pyplumio-0.7.8}/docs/source/mixers_thermostats.rst +0 -0
  77. {pyplumio-0.7.6 → pyplumio-0.7.8}/docs/source/protocol.rst +0 -0
  78. {pyplumio-0.7.6 → pyplumio-0.7.8}/docs/source/reading.rst +0 -0
  79. {pyplumio-0.7.6 → pyplumio-0.7.8}/docs/source/schedules.rst +0 -0
  80. {pyplumio-0.7.6 → pyplumio-0.7.8}/docs/source/writing.rst +0 -0
  81. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/const.py +0 -0
  82. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/exceptions.py +0 -0
  83. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/helpers/__init__.py +0 -0
  84. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/parameters/custom/ecomax_350p2_zf.py +0 -0
  85. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/parameters/custom/ecomax_860d3_hb.py +0 -0
  86. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/parameters/custom/ecomax_860p4_nm_touch.py +0 -0
  87. {pyplumio-0.7.6 → pyplumio-0.7.8}/pyplumio/py.typed +0 -0
  88. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/__init__.py +0 -0
  89. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/devices/__init__.py +0 -0
  90. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/devices/test_ecoster.py +0 -0
  91. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/devices/test_init.py +0 -0
  92. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/devices/test_thermostat.py +0 -0
  93. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/frames/test_init.py +0 -0
  94. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/frames/test_messages.py +0 -0
  95. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/frames/test_requests.py +0 -0
  96. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/frames/test_responses.py +0 -0
  97. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/helpers/__init__.py +0 -0
  98. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/helpers/test_async_cache.py +0 -0
  99. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/helpers/test_event_manager.py +0 -0
  100. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/helpers/test_task_manager.py +0 -0
  101. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/helpers/test_uid.py +0 -0
  102. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/parameters/__init__.py +0 -0
  103. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/parameters/custom/__init__.py +0 -0
  104. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/parameters/custom/test_ecomax_350p2_zf.py +0 -0
  105. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/parameters/custom/test_ecomax_860d3_hb.py +0 -0
  106. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/parameters/custom/test_ecomax_860p4_nm_touch.py +0 -0
  107. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/parameters/test_ecomax.py +0 -0
  108. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/parameters/test_init.py +0 -0
  109. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/parameters/test_mixers.py +0 -0
  110. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/parameters/test_thermostats.py +0 -0
  111. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/ruff.toml +0 -0
  112. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/structures/__init__.py +0 -0
  113. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/structures/test_alerts.py +0 -0
  114. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/structures/test_ecomax_parameters.py +0 -0
  115. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/structures/test_ecomax_service_parameters.py +0 -0
  116. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/structures/test_frame_versions.py +0 -0
  117. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/structures/test_mixer_parameters.py +0 -0
  118. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/structures/test_product_info.py +0 -0
  119. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/structures/test_program_version.py +0 -0
  120. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/structures/test_schedules.py +0 -0
  121. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/test_connection.py +0 -0
  122. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/test_data_types.py +0 -0
  123. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/test_filters.py +0 -0
  124. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/test_init.py +0 -0
  125. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/test_protocol.py +0 -0
  126. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/test_stream.py +0 -0
  127. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/test_utils.py +0 -0
  128. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/messages/regulator_data.json +0 -0
  129. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/messages/sensor_data.json +0 -0
  130. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/parameters/ecomax_350p2_zf.json +0 -0
  131. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/parameters/ecomax_860d3_hb.json +0 -0
  132. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/parameters/ecomax_860p4_nm_touch.json +0 -0
  133. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/requests/alerts.json +0 -0
  134. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/requests/ecomax_control.json +0 -0
  135. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/requests/ecomax_parameters.json +0 -0
  136. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/requests/ecomax_service_parameters.json +0 -0
  137. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/requests/mixer_parameters.json +0 -0
  138. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/requests/set_ecomax_parameter.json +0 -0
  139. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/requests/set_ecomax_service_parameter.json +0 -0
  140. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/requests/set_mixer_parameter.json +0 -0
  141. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/requests/set_schedule.json +0 -0
  142. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/requests/set_thermostat_parameter.json +0 -0
  143. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/requests/thermostat_parameters.json +0 -0
  144. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/responses/alerts.json +0 -0
  145. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/responses/device_available.json +0 -0
  146. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/responses/ecomax_parameters.json +0 -0
  147. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/responses/ecomax_service_parameters.json +0 -0
  148. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/responses/mixer_parameters.json +0 -0
  149. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/responses/password.json +0 -0
  150. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/responses/program_version.json +0 -0
  151. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/responses/regulator_data_schema.json +0 -0
  152. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/responses/schedules.json +0 -0
  153. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/responses/thermostat_parameters.json +0 -0
  154. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/responses/uid.json +0 -0
  155. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/unknown/unknown_ecomax_parameter.json +0 -0
  156. {pyplumio-0.7.6 → pyplumio-0.7.8}/tests/testdata/unknown/unknown_mixer_parameter.json +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: PyPlumIO
3
- Version: 0.7.6
3
+ Version: 0.7.8
4
4
  Summary: PyPlumIO is a native ecoNET library for Plum ecoMAX controllers.
5
5
  Project-URL: Documentation, https://pyplumio.denpa.pro
6
6
  Project-URL: Source Code, https://github.com/denpamusic/PyPlumIO
@@ -21,6 +21,8 @@ Classifier: Topic :: Software Development :: Libraries
21
21
  Classifier: Typing :: Typed
22
22
  Requires-Python: >=3.11
23
23
  Requires-Dist: serialx>=1.10.0
24
+ Provides-Extra: cli
25
+ Requires-Dist: prompt-toolkit>=3.0.43; extra == 'cli'
24
26
  Description-Content-Type: text/markdown
25
27
 
26
28
  # PyPlumIO is a native ecoNET library for Plum ecoMAX controllers
@@ -64,6 +66,25 @@ through network by using RS-485 to Ethernet/WiFi converter.
64
66
  - [Communication](https://pyplumio.denpa.pro/protocol.html#communication)
65
67
  - [Versioning](https://pyplumio.denpa.pro/protocol.html#versioning)
66
68
  - [Supported frames](https://pyplumio.denpa.pro/frames.html)
69
+ - [CLI Parameter Mapper](https://pyplumio.denpa.pro/cli.html)
70
+
71
+ ## Parameter Mapping CLI
72
+
73
+ PyPlumIO provides an interactive terminal utility to help map service parameters
74
+ for ecoMAX controllers and generate custom parameter modules.
75
+
76
+ On **Windows**, you can download the standalone `pyplumio.exe` executable directly from
77
+ the [GitHub Releases](https://github.com/denpamusic/PyPlumIO/releases) page without
78
+ installing Python.
79
+
80
+ Alternatively, install PyPlumIO with the `cli` extra and run it via Python:
81
+
82
+ ```bash
83
+ pip install "pyplumio[cli]"
84
+ python -m pyplumio
85
+ ```
86
+
87
+ See the [CLI documentation](https://pyplumio.denpa.pro/cli.html) for details.
67
88
 
68
89
  ## Quickstart
69
90
 
@@ -39,6 +39,25 @@ through network by using RS-485 to Ethernet/WiFi converter.
39
39
  - [Communication](https://pyplumio.denpa.pro/protocol.html#communication)
40
40
  - [Versioning](https://pyplumio.denpa.pro/protocol.html#versioning)
41
41
  - [Supported frames](https://pyplumio.denpa.pro/frames.html)
42
+ - [CLI Parameter Mapper](https://pyplumio.denpa.pro/cli.html)
43
+
44
+ ## Parameter Mapping CLI
45
+
46
+ PyPlumIO provides an interactive terminal utility to help map service parameters
47
+ for ecoMAX controllers and generate custom parameter modules.
48
+
49
+ On **Windows**, you can download the standalone `pyplumio.exe` executable directly from
50
+ the [GitHub Releases](https://github.com/denpamusic/PyPlumIO/releases) page without
51
+ installing Python.
52
+
53
+ Alternatively, install PyPlumIO with the `cli` extra and run it via Python:
54
+
55
+ ```bash
56
+ pip install "pyplumio[cli]"
57
+ python -m pyplumio
58
+ ```
59
+
60
+ See the [CLI documentation](https://pyplumio.denpa.pro/cli.html) for details.
42
61
 
43
62
  ## Quickstart
44
63
 
@@ -0,0 +1,161 @@
1
+ Command Line Interface
2
+ ======================
3
+
4
+ PyPlumIO includes an interactive command-line utility for mapping ecoMAX controller
5
+ service parameters and generating custom parameter modules.
6
+
7
+ Installation
8
+ ------------
9
+
10
+ Windows Executable
11
+ ~~~~~~~~~~~~~~~~~~
12
+
13
+ On Windows, download the standalone ``pyplumio.exe`` executable from the
14
+ `GitHub Releases <https://github.com/denpamusic/PyPlumIO/releases>`_ page. No Python
15
+ installation is required—double-click ``pyplumio.exe`` or run it from Command Prompt
16
+ or PowerShell. Generated files (or ``<model_slug>.zip``) are saved in the working
17
+ directory where ``pyplumio.exe`` is launched unless ``--output`` is specified.
18
+
19
+ Python Package
20
+ ~~~~~~~~~~~~~~
21
+
22
+ Alternatively, install PyPlumIO with the ``cli`` extra (which includes optional
23
+ dependencies such as ``prompt_toolkit``):
24
+
25
+ .. code-block:: console
26
+
27
+ $ pip install "pyplumio[cli]"
28
+ # or with uv
29
+ $ uv add "pyplumio[cli]"
30
+
31
+ Usage
32
+ -----
33
+
34
+ Run the CLI using the standalone executable, console script, or Python module execution:
35
+
36
+ .. code-block:: console
37
+
38
+ $ pyplumio
39
+ # or
40
+ $ python -m pyplumio
41
+
42
+ Command-Line Options
43
+ --------------------
44
+
45
+ The CLI supports the following arguments:
46
+
47
+ .. code-block:: text
48
+
49
+ usage: pyplumio [-h] [--url URL] [--output DIR] [--interval SECONDS] [--baudrate BAUDRATE] [-z]
50
+
51
+ options:
52
+ -h, --help show this help message and exit
53
+ --url URL Connection URL (e.g. socket://localhost:8899 or /dev/ttyUSB0).
54
+ If omitted, you will be prompted interactively.
55
+ --output DIR Output directory for generated files (default: current working directory).
56
+ --interval SECONDS Polling interval in seconds (default: 2.0).
57
+ --baudrate BAUDRATE Serial baudrate (default: 115200).
58
+ -z, --zip Save output as a ZIP archive.
59
+
60
+ Interactive Connection Setup
61
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62
+
63
+ If ``--url`` is omitted, the CLI will guide you through configuring the connection:
64
+
65
+ 1. **Connection Type**: Choose between ``tcp`` and ``serial``.
66
+ 2. **TCP Settings**: Enter host and port (default: ``8899``).
67
+ 3. **Serial Settings**: Enter the serial port path (e.g., ``/dev/ttyUSB0`` or ``COM3``).
68
+
69
+ Workflow & Parameter Mapping
70
+ ----------------------------
71
+
72
+ During startup, the CLI connects to the controller, retrieves the product
73
+ information and model name, and requests the initial service parameters before
74
+ opening the full-screen interface. Progress messages are written to standard
75
+ error at each stage: connecting to the URL, requesting product info with attempt
76
+ counters (e.g. ``(1/3)``), requesting service parameters for the detected
77
+ model, and starting the interface. Each request attempt uses a 5-second timeout
78
+ and up to 3 attempts (up to about 30 seconds total in the worst case). If the
79
+ controller never answers service parameters requests after all attempts, the
80
+ CLI exits before opening the interface with an error explaining that the
81
+ controller may not support them. If the connection drops at any point during
82
+ this phase, a connection-lost error is reported instead. Once startup succeeds,
83
+ the full-screen interface opens with the parameter table already filled and keeps
84
+ polling in the background.
85
+
86
+ The interface consists of:
87
+
88
+ - **Header**: Inverted top bar showing connected controller model, product ID, connection URL, and last update timestamp.
89
+ - **Table**: Monospace scrollable list showing parameter indices, mapped names, current values, minimums, and maximums. Recently changed parameters are highlighted with inverted colors.
90
+ - **Live Preview**: Real-time 4-line framed box docked above the input bar displaying active parameter fields, raw values, and live calculations.
91
+ - **Status Bar**: Inverted bar positioned below the input prompt and directly above the hotkey bar displaying validation messages, available units, and connection status.
92
+ - **Hotkey Bar**: Bottom bar displaying keyboard shortcuts (``^S`` Save, ``^Q`` Quit, ``Esc`` Cancel, ``↑/↓`` Scroll, ``PgUp/PgDn`` Page, ``Tab`` Complete).
93
+
94
+ Interactive Wizard
95
+ ~~~~~~~~~~~~~~~~~~
96
+
97
+ At the bottom of the screen, a wizard guides you through naming and configuring each parameter:
98
+
99
+ 1. **Index**: Enter the parameter index from the table. While navigating the wizard past this step, table row ordering is frozen to prevent rows from jumping while typing.
100
+ 2. **Name**: Enter a unique snake_case name (e.g. ``heating_temp``):
101
+ - Standard ecoMAX parameter names for the connected device are offered as autocompletion (substring match; names already used by other indices are left out).
102
+ - If the name is already used by another parameter index, it is rejected.
103
+ - Choosing or typing a standard name pre-fills the **Type**, **Offset**, **Step**, and **Unit** defaults from that parameter's standard description. Re-editing an already-mapped parameter and keeping its name preserves its existing settings as defaults. Sharing a name with a standard parameter is intended, so there is no warning any more.
104
+ - Submitting an empty name deletes the parameter (and its comment) if it is already mapped, or cancels and returns to the index prompt if it has not been mapped yet.
105
+ 3. **Type**: Select ``number`` or ``switch`` (defaults to the pre-filled template type, or ``switch`` if minimum is 0 and maximum is 1, otherwise ``number``).
106
+ 4. **Number Settings**: If configuring a number (defaults come from the matched template or existing mapping, or fall back to ``0``, ``1``, and ``none``):
107
+ - **Offset**: Raw offset to subtract (default: ``0``).
108
+ - **Step**: Multiplier/step (default: ``1``; e.g. ``1``, ``0.1``, ``10``).
109
+ - **Unit**: Physical unit of measurement (supports autocompletion for unit values such as ``°C``, ``kW``, ``rpm``, ``%``, etc., or enter ``none`` to clear a pre-filled unit).
110
+ 5. **Comment**: Enter an optional comment (or leave empty for none). When re-editing a parameter that already has a comment (either loaded from an existing custom parameter module or added in the current session), the prompt is pre-filled with the existing comment. Comments are written as wrapped ``# ...`` lines directly above the parameter entry in the generated module.
111
+ 6. **Confirm**: Confirm the decoded value and range match your controller display (``[y/N]``).
112
+ 7. Press ``Esc`` at any point to cancel the wizard.
113
+
114
+ Connection Resilience
115
+ ---------------------
116
+
117
+ If the serial connection or TCP bridge drops during a session, the CLI automatically stops background polling and notifies you via the status line:
118
+
119
+ .. code-block:: text
120
+
121
+ Connection lost. Reconnecting in background in 20 seconds...
122
+
123
+ The CLI automatically retries the connection every 20 seconds in the background while keeping the interface fully responsive. Once reconnected, it displays ``Connection restored.`` and resumes polling. Even when disconnected, you can review mapped parameters, continue editing, and press ``Ctrl+S`` to save the files from the last received frame.
124
+
125
+ Saving & Output Files
126
+ ---------------------
127
+
128
+ Press ``Ctrl+S`` to save generated files. At least one parameter must be mapped; attempting to save with no mapped parameters will show:
129
+
130
+ .. code-block:: text
131
+
132
+ Nothing to save: map at least one parameter first.
133
+
134
+ Unless ``-z`` / ``--zip`` was passed on the command line, you will be asked ``Save as a ZIP archive? [y/N]``:
135
+
136
+ - Answering ``n`` (or pressing Enter) writes the three generated files directly into the ``<output>`` directory tree. If ``<output>/pyplumio/parameters/custom/<model_slug>.py`` already exists, you will be prompted to confirm overwrite (``Overwrite existing <model_slug>.py? [y/N]``).
137
+ - Answering ``y`` (or starting the CLI with ``-z`` / ``--zip``) saves a single ``<output>/<model_slug>.zip`` archive containing the same repository-relative paths inside, which can be attached directly to a GitHub issue instead of opening a PR. If ``<output>/<model_slug>.zip`` already exists, you will be prompted to confirm overwrite (``Overwrite existing <model_slug>.zip? [y/N]``).
138
+
139
+ The utility produces the following three files (either on disk or inside ``<output>/<model_slug>.zip``):
140
+
141
+ 1. **Custom Parameter Module**:
142
+ ``<output>/pyplumio/parameters/custom/<model_slug>.py``
143
+ Contains the ``CustomParameters`` class definition, model signature, and descriptions dictionary.
144
+
145
+ 2. **Test Module**:
146
+ ``<output>/tests/parameters/custom/test_<model_slug>.py``
147
+ Parametrized pytest tests verifying every mapped parameter against real frame data.
148
+
149
+ 3. **Captured Frame Test Data**:
150
+ ``<output>/tests/testdata/parameters/<model_slug>.json``
151
+ Raw frame capture used for reproducible testing.
152
+
153
+ Press ``Ctrl+Q`` to exit the application cleanly.
154
+
155
+ Contributing Mapped Parameters
156
+ ------------------------------
157
+
158
+ Once you have mapped parameters for your controller model:
159
+
160
+ 1. Open a pull request against `PyPlumIO <https://github.com/denpamusic/PyPlumIO/>`_ adding the generated files.
161
+ 2. Alternatively, create an issue on GitHub and attach the generated ``<model_slug>.zip`` archive (or the three generated files).
@@ -55,6 +55,7 @@ Documentation
55
55
  schedules
56
56
  protocol
57
57
  frames
58
+ cli
58
59
 
59
60
  .. autosummary::
60
61
  :toctree: _autosummary
@@ -75,7 +75,7 @@ def serial_for_url(
75
75
  )
76
76
 
77
77
 
78
- __all__ = [
78
+ __all__ = (
79
79
  "__version__",
80
80
  "version",
81
81
  "AlertType",
@@ -117,4 +117,4 @@ __all__ = [
117
117
  "responses",
118
118
  "requests",
119
119
  "serial_for_url",
120
- ]
120
+ )
@@ -0,0 +1,10 @@
1
+ """Contains entry point for PyPlumIO CLI."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import sys
6
+
7
+ from pyplumio.cli import main
8
+
9
+ if __name__ == "__main__":
10
+ sys.exit(main())
@@ -0,0 +1,118 @@
1
+ """Contains PyPlumIO command line interface."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import asyncio
7
+ from collections.abc import Sequence
8
+ from contextlib import suppress
9
+ import ctypes
10
+ from enum import IntEnum, unique
11
+ import os
12
+ from pathlib import Path
13
+ import sys
14
+ import traceback
15
+ from typing import Final
16
+
17
+ from pyplumio.cli.session import DEFAULT_INTERVAL_SECONDS
18
+ from pyplumio.connection import DEFAULT_BAUDRATE
19
+
20
+ MAX_CONSOLE_PROCESSES: Final = 4
21
+
22
+
23
+ @unique
24
+ class _ExitCode(IntEnum):
25
+ """Contains exit codes."""
26
+
27
+ SUCCESS = 0
28
+ FAILURE = 1
29
+ SIGINT = 130
30
+
31
+
32
+ def _is_standalone_windows_console() -> bool:
33
+ """Return True if running in a dedicated Windows console window."""
34
+ if (
35
+ (windll := getattr(ctypes, "windll", None)) is None
36
+ or not sys.stdin
37
+ or not sys.stdin.isatty()
38
+ ):
39
+ return False
40
+
41
+ try:
42
+ process_ids = (ctypes.c_uint32 * MAX_CONSOLE_PROCESSES)()
43
+ count = int(
44
+ windll.kernel32.GetConsoleProcessList(process_ids, MAX_CONSOLE_PROCESSES)
45
+ )
46
+ except (AttributeError, OSError):
47
+ return False
48
+
49
+ own_pids = (
50
+ {os.getpid(), os.getppid()} if getattr(sys, "frozen", False) else {os.getpid()}
51
+ )
52
+ return 0 < count <= len(own_pids) and set(process_ids[:count]) <= own_pids
53
+
54
+
55
+ def _pause_before_exit() -> None:
56
+ """Pause before exiting so users can read error messages."""
57
+ if _is_standalone_windows_console():
58
+ sys.stderr.flush()
59
+ with suppress(EOFError, KeyboardInterrupt):
60
+ input("\nPress Enter to exit...")
61
+
62
+
63
+ def _parse_system_exit(err: SystemExit) -> int:
64
+ """Convert SystemExit code to an integer exit status."""
65
+ if isinstance(err.code, int):
66
+ return err.code
67
+
68
+ return _ExitCode.SUCCESS if err.code is None else _ExitCode.FAILURE
69
+
70
+
71
+ def _run_cli(argv: Sequence[str] | None) -> int:
72
+ """Parse arguments and execute the CLI application."""
73
+ try:
74
+ from pyplumio.cli.app import run_app # noqa: PLC0415
75
+ except ImportError:
76
+ sys.stderr.write(
77
+ 'PyPlumIO CLI requires extra dependencies: pip install "pyplumio[cli]"\n'
78
+ )
79
+ return _ExitCode.FAILURE
80
+
81
+ parser = argparse.ArgumentParser(description="PyPlumIO parameter mapper.")
82
+ parser.add_argument("--url", default=None, help="connection URL")
83
+ parser.add_argument("--output", type=Path, default=Path.cwd(), help="output root")
84
+ parser.add_argument(
85
+ "--interval",
86
+ type=float,
87
+ default=DEFAULT_INTERVAL_SECONDS,
88
+ help="poll interval",
89
+ )
90
+ parser.add_argument(
91
+ "--baudrate", type=int, default=DEFAULT_BAUDRATE, help="baudrate"
92
+ )
93
+ parser.add_argument(
94
+ "-z", "--zip", action="store_true", help="save output as a ZIP archive"
95
+ )
96
+ try:
97
+ return asyncio.run(run_app(parser.parse_args(argv)))
98
+ except KeyboardInterrupt:
99
+ return _ExitCode.SIGINT
100
+ except EOFError:
101
+ return _ExitCode.FAILURE
102
+ except SystemExit as err:
103
+ return _parse_system_exit(err)
104
+ except Exception:
105
+ traceback.print_exc()
106
+ return _ExitCode.FAILURE
107
+
108
+
109
+ def main(argv: Sequence[str] | None = None) -> int:
110
+ """Run PyPlumIO command line interface."""
111
+ exit_code = _run_cli(argv)
112
+ if exit_code not in (_ExitCode.SUCCESS, _ExitCode.SIGINT):
113
+ _pause_before_exit()
114
+
115
+ return exit_code
116
+
117
+
118
+ __all__ = ("main",)
@@ -0,0 +1,213 @@
1
+ """Contains PyPlumIO CLI application runner and connection prompts."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ from collections.abc import Iterator, Sequence
7
+ from contextlib import contextmanager, suppress
8
+ from enum import StrEnum, unique
9
+ import inspect
10
+ import logging
11
+ from pathlib import Path
12
+ import sys
13
+ from typing import Final
14
+
15
+ from prompt_toolkit.application import Application
16
+ from prompt_toolkit.completion import WordCompleter
17
+ from prompt_toolkit.shortcuts import PromptSession
18
+ from prompt_toolkit.validation import Validator
19
+ from serialx import SerialException
20
+
21
+ from pyplumio.cli.codegen import custom_module_path, extract_comments
22
+ from pyplumio.cli.model import ParameterTable
23
+ from pyplumio.cli.session import Session
24
+ from pyplumio.cli.state import AppState
25
+ from pyplumio.cli.ui import create_app
26
+ from pyplumio.exceptions import PyPlumIOError
27
+ from pyplumio.parameters import ParameterValues
28
+ from pyplumio.parameters.custom import (
29
+ CustomParameters,
30
+ load_custom_parameters,
31
+ model_slug,
32
+ )
33
+
34
+
35
+ @unique
36
+ class _ConnectionType(StrEnum):
37
+ """Contains connection types."""
38
+
39
+ TCP = "tcp"
40
+ SERIAL = "serial"
41
+
42
+
43
+ DEFAULT_PORT: Final = 8899
44
+ MAX_PORT: Final = 65535
45
+ AVAILABLE_CONNECTION_TYPES: Final = ", ".join(_ConnectionType)
46
+ CONNECTION_TYPE_COMPLETER: Final = WordCompleter(list(_ConnectionType))
47
+ CONNECTION_TYPE_VALIDATOR: Final = Validator.from_callable(
48
+ lambda text: text.strip().lower() in list(_ConnectionType),
49
+ error_message=f"Must be one of the following: {AVAILABLE_CONNECTION_TYPES}",
50
+ )
51
+ HOST_VALIDATOR: Final = Validator.from_callable(
52
+ lambda text: bool(text.strip()), error_message="Host cannot be empty"
53
+ )
54
+ PORT_VALIDATOR: Final = Validator.from_callable(
55
+ lambda text: (
56
+ not text.strip() or (text.strip().isdigit() and 1 <= int(text) <= MAX_PORT)
57
+ ),
58
+ error_message=f"Port must be 1-{MAX_PORT}",
59
+ )
60
+ URL_VALIDATOR: Final = Validator.from_callable(
61
+ lambda text: bool(text.strip()), error_message="URL cannot be empty"
62
+ )
63
+
64
+
65
+ class _StatusLogHandler(logging.Handler):
66
+ """Represents a log handler routing warnings to app status."""
67
+
68
+ __slots__ = ("_state",)
69
+
70
+ _state: AppState
71
+
72
+ def __init__(self, state: AppState) -> None:
73
+ """Initialize the status log handler."""
74
+ super().__init__(level=logging.WARNING)
75
+ self._state = state
76
+
77
+ def emit(self, record: logging.LogRecord) -> None:
78
+ """Emit log message to app status."""
79
+ self._state.status = self.format(record)
80
+ if self._state.application:
81
+ self._state.application.invalidate()
82
+
83
+
84
+ @contextmanager
85
+ def _capture_logs(state: AppState) -> Iterator[None]:
86
+ """Route pyplumio logger warnings to app status while active."""
87
+ pyplumio_logger = logging.getLogger("pyplumio")
88
+ original_handlers = pyplumio_logger.handlers[:]
89
+ original_propagate = pyplumio_logger.propagate
90
+ pyplumio_logger.handlers = [_StatusLogHandler(state)]
91
+ pyplumio_logger.propagate = False
92
+ try:
93
+ yield
94
+ finally:
95
+ pyplumio_logger.handlers = original_handlers
96
+ pyplumio_logger.propagate = original_propagate
97
+
98
+
99
+ def _format_error(err: BaseException) -> str:
100
+ """Return formatted error message with cause fallback."""
101
+ if message := str(err):
102
+ return message
103
+
104
+ if err.__cause__:
105
+ return f"{type(err).__name__}: {err.__cause__}"
106
+
107
+ return type(err).__name__
108
+
109
+
110
+ def _write_status(message: str) -> None:
111
+ """Write status message to standard error."""
112
+ sys.stderr.write(f"{message}\n")
113
+ sys.stderr.flush()
114
+
115
+
116
+ def _load_comments(
117
+ custom_parameters: CustomParameters, output_dir: Path, slug: str
118
+ ) -> dict[int, str]:
119
+ """Load parameter comments from output directory or module source."""
120
+ path = custom_module_path(output_dir, slug)
121
+ if not path.is_file() and (
122
+ source_file := inspect.getsourcefile(type(custom_parameters))
123
+ ):
124
+ path = Path(source_file)
125
+
126
+ if path.is_file():
127
+ with suppress(OSError):
128
+ return extract_comments(path.read_text(encoding="utf-8"))
129
+
130
+ return {}
131
+
132
+
133
+ async def prompt_connection_url(
134
+ session: PromptSession[str] | None = None,
135
+ ) -> str:
136
+ """Prompt user for connection details and return the connection URL."""
137
+ if not session:
138
+ session = PromptSession()
139
+
140
+ connection_type = await session.prompt_async(
141
+ f"Connection type ({AVAILABLE_CONNECTION_TYPES}): ",
142
+ completer=CONNECTION_TYPE_COMPLETER,
143
+ validator=CONNECTION_TYPE_VALIDATOR,
144
+ )
145
+ connection_type = connection_type.strip().lower()
146
+
147
+ if connection_type == _ConnectionType.TCP:
148
+ host = await session.prompt_async("Host: ", validator=HOST_VALIDATOR)
149
+ host = host.strip()
150
+ port = await session.prompt_async(
151
+ f"Port [{DEFAULT_PORT}]: ", validator=PORT_VALIDATOR
152
+ )
153
+ if not (port := port.strip()):
154
+ port = str(DEFAULT_PORT)
155
+
156
+ return f"socket://{host}:{port}"
157
+
158
+ url = await session.prompt_async(
159
+ "Device URL (e.g. /dev/ttyUSB0, COM3): ", validator=URL_VALIDATOR
160
+ )
161
+ return url.strip()
162
+
163
+
164
+ async def run_app(args: argparse.Namespace) -> int:
165
+ """Run PyPlumIO CLI application."""
166
+ url = args.url or await prompt_connection_url()
167
+ output_dir = Path(args.output)
168
+ table = ParameterTable()
169
+ app: Application[None] | None = None
170
+
171
+ def on_update(parameters: Sequence[tuple[int, ParameterValues]]) -> None:
172
+ table.update(parameters)
173
+ if app:
174
+ app.invalidate()
175
+
176
+ session = Session(
177
+ url=url,
178
+ baudrate=args.baudrate,
179
+ interval=args.interval,
180
+ on_update=on_update,
181
+ on_status=_write_status,
182
+ )
183
+ try:
184
+ product_info = await session.connect()
185
+ if custom_parameters := await load_custom_parameters(product_info):
186
+ comments = _load_comments(
187
+ custom_parameters, output_dir, model_slug(product_info.model)
188
+ )
189
+ for index, description in custom_parameters.descriptions.items():
190
+ table.set_description(
191
+ index, description, comment=comments.get(index, "")
192
+ )
193
+
194
+ table.overrides = tuple(custom_parameters.overrides)
195
+
196
+ app, state = create_app(session, table, output_dir, zip_output=args.zip)
197
+ with _capture_logs(state):
198
+ _write_status("Starting interface...")
199
+ await app.run_async()
200
+
201
+ except (PyPlumIOError, SerialException, OSError, ValueError) as err:
202
+ sys.stderr.write(f"Error: {_format_error(err)}\n")
203
+ return 1
204
+ finally:
205
+ await session.close()
206
+
207
+ return 0
208
+
209
+
210
+ __all__ = (
211
+ "prompt_connection_url",
212
+ "run_app",
213
+ )