PyPlumIO 0.7.8.post1__tar.gz → 0.7.9__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 (163) hide show
  1. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/PKG-INFO +2 -2
  2. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/README.md +1 -1
  3. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/source/cli.rst +23 -5
  4. pyplumio-0.7.9/docs/source/custom_parameters.rst +195 -0
  5. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/source/frames.rst +3 -1
  6. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/source/index.rst +1 -0
  7. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/cli/app.py +81 -12
  8. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/cli/codegen.py +85 -94
  9. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/cli/model.py +3 -4
  10. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/cli/session.py +3 -1
  11. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/cli/state.py +7 -45
  12. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/cli/ui.py +23 -2
  13. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/const.py +3 -0
  14. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/devices/ecomax.py +74 -57
  15. pyplumio-0.7.9/pyplumio/parameters/custom/__init__.py +261 -0
  16. pyplumio-0.7.9/pyplumio/parameters/custom/ecomax_350p2_zf.py +86 -0
  17. pyplumio-0.7.9/pyplumio/parameters/custom/ecomax_860d3_hb.py +25 -0
  18. pyplumio-0.7.9/pyplumio/parameters/custom/ecomax_860p4_nm_touch.py +99 -0
  19. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/parameters/ecomax.py +2 -2
  20. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyproject.toml +1 -1
  21. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/cli/conftest.py +48 -51
  22. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/cli/test_app.py +324 -41
  23. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/cli/test_codegen.py +117 -92
  24. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/cli/test_model.py +1 -1
  25. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/cli/test_session.py +7 -4
  26. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/cli/test_state.py +57 -143
  27. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/cli/test_ui.py +75 -35
  28. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/devices/test_ecomax.py +265 -1
  29. pyplumio-0.7.9/tests/parameters/custom/test_ecomax_350p2_zf.py +147 -0
  30. pyplumio-0.7.9/tests/parameters/custom/test_init.py +293 -0
  31. pyplumio-0.7.9/tests/test_const.py +15 -0
  32. pyplumio-0.7.9/tests/testdata/parameters/ecomax_350p2_zf.json +20 -0
  33. pyplumio-0.7.8.post1/pyplumio/parameters/custom/__init__.py +0 -135
  34. pyplumio-0.7.8.post1/pyplumio/parameters/custom/ecomax_350p2_zf.py +0 -80
  35. pyplumio-0.7.8.post1/pyplumio/parameters/custom/ecomax_860d3_hb.py +0 -80
  36. pyplumio-0.7.8.post1/pyplumio/parameters/custom/ecomax_860p4_nm_touch.py +0 -301
  37. pyplumio-0.7.8.post1/tests/parameters/custom/test_ecomax_350p2_zf.py +0 -100
  38. pyplumio-0.7.8.post1/tests/parameters/custom/test_init.py +0 -117
  39. pyplumio-0.7.8.post1/tests/testdata/parameters/ecomax_350p2_zf.json +0 -19
  40. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/.gitignore +0 -0
  41. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/LICENSE +0 -0
  42. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/Makefile +0 -0
  43. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/make.bat +0 -0
  44. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/source/callbacks.rst +0 -0
  45. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/source/conf.py +0 -0
  46. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/source/connecting.rst +0 -0
  47. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/source/mixers_thermostats.rst +0 -0
  48. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/source/protocol.rst +0 -0
  49. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/source/reading.rst +0 -0
  50. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/source/schedules.rst +0 -0
  51. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/docs/source/writing.rst +0 -0
  52. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/__init__.py +0 -0
  53. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/__main__.py +0 -0
  54. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/cli/__init__.py +0 -0
  55. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/connection.py +0 -0
  56. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/data_types.py +0 -0
  57. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/devices/__init__.py +0 -0
  58. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/devices/ecoster.py +0 -0
  59. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/devices/mixer.py +0 -0
  60. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/devices/thermostat.py +0 -0
  61. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/exceptions.py +0 -0
  62. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/filters.py +0 -0
  63. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/frames/__init__.py +0 -0
  64. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/frames/messages.py +0 -0
  65. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/frames/requests.py +0 -0
  66. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/frames/responses.py +0 -0
  67. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/helpers/__init__.py +0 -0
  68. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/helpers/async_cache.py +0 -0
  69. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/helpers/event_manager.py +0 -0
  70. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/helpers/task_manager.py +0 -0
  71. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/parameters/__init__.py +0 -0
  72. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/parameters/mixer.py +0 -0
  73. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/parameters/thermostat.py +0 -0
  74. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/protocol.py +0 -0
  75. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/py.typed +0 -0
  76. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/stream.py +0 -0
  77. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/__init__.py +0 -0
  78. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/alerts.py +0 -0
  79. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/ecomax_parameters.py +0 -0
  80. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/ecomax_service_parameters.py +0 -0
  81. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/frame_versions.py +0 -0
  82. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/mixer_parameters.py +0 -0
  83. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/network_info.py +0 -0
  84. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/product_info.py +0 -0
  85. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/program_version.py +0 -0
  86. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/regulator_data.py +0 -0
  87. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/regulator_data_schema.py +0 -0
  88. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/schedules.py +0 -0
  89. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/sensor_data.py +0 -0
  90. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/structures/thermostat_parameters.py +0 -0
  91. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/pyplumio/utils.py +0 -0
  92. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/__init__.py +0 -0
  93. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/cli/__init__.py +0 -0
  94. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/cli/test_init.py +0 -0
  95. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/conftest.py +0 -0
  96. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/devices/__init__.py +0 -0
  97. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/devices/test_ecoster.py +0 -0
  98. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/devices/test_init.py +0 -0
  99. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/devices/test_mixer.py +0 -0
  100. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/devices/test_thermostat.py +0 -0
  101. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/frames/test_init.py +0 -0
  102. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/frames/test_messages.py +0 -0
  103. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/frames/test_requests.py +0 -0
  104. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/frames/test_responses.py +0 -0
  105. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/helpers/__init__.py +0 -0
  106. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/helpers/test_async_cache.py +0 -0
  107. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/helpers/test_event_manager.py +0 -0
  108. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/helpers/test_task_manager.py +0 -0
  109. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/helpers/test_uid.py +0 -0
  110. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/parameters/__init__.py +0 -0
  111. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/parameters/custom/__init__.py +0 -0
  112. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/parameters/custom/test_ecomax_860d3_hb.py +0 -0
  113. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/parameters/custom/test_ecomax_860p4_nm_touch.py +0 -0
  114. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/parameters/test_ecomax.py +0 -0
  115. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/parameters/test_init.py +0 -0
  116. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/parameters/test_mixers.py +0 -0
  117. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/parameters/test_thermostats.py +0 -0
  118. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/ruff.toml +0 -0
  119. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/structures/__init__.py +0 -0
  120. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/structures/test_alerts.py +0 -0
  121. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/structures/test_ecomax_parameters.py +0 -0
  122. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/structures/test_ecomax_service_parameters.py +0 -0
  123. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/structures/test_frame_versions.py +0 -0
  124. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/structures/test_mixer_parameters.py +0 -0
  125. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/structures/test_product_info.py +0 -0
  126. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/structures/test_program_version.py +0 -0
  127. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/structures/test_schedules.py +0 -0
  128. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/test_connection.py +0 -0
  129. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/test_data_types.py +0 -0
  130. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/test_filters.py +0 -0
  131. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/test_init.py +0 -0
  132. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/test_main.py +0 -0
  133. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/test_protocol.py +0 -0
  134. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/test_stream.py +0 -0
  135. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/test_utils.py +0 -0
  136. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/messages/regulator_data.json +0 -0
  137. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/messages/sensor_data.json +0 -0
  138. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/parameters/ecomax_860d3_hb.json +0 -0
  139. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/parameters/ecomax_860p4_nm_touch.json +0 -0
  140. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/requests/alerts.json +0 -0
  141. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/requests/ecomax_control.json +0 -0
  142. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/requests/ecomax_parameters.json +0 -0
  143. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/requests/ecomax_service_parameters.json +0 -0
  144. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/requests/mixer_parameters.json +0 -0
  145. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/requests/set_ecomax_parameter.json +0 -0
  146. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/requests/set_ecomax_service_parameter.json +0 -0
  147. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/requests/set_mixer_parameter.json +0 -0
  148. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/requests/set_schedule.json +0 -0
  149. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/requests/set_thermostat_parameter.json +0 -0
  150. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/requests/thermostat_parameters.json +0 -0
  151. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/responses/alerts.json +0 -0
  152. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/responses/device_available.json +0 -0
  153. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/responses/ecomax_parameters.json +0 -0
  154. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/responses/ecomax_service_parameters.json +0 -0
  155. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/responses/mixer_parameters.json +0 -0
  156. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/responses/password.json +0 -0
  157. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/responses/program_version.json +0 -0
  158. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/responses/regulator_data_schema.json +0 -0
  159. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/responses/schedules.json +0 -0
  160. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/responses/thermostat_parameters.json +0 -0
  161. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/responses/uid.json +0 -0
  162. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/tests/testdata/unknown/unknown_ecomax_parameter.json +0 -0
  163. {pyplumio-0.7.8.post1 → pyplumio-0.7.9}/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.8.post1
3
+ Version: 0.7.9
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
@@ -65,7 +65,7 @@ through network by using RS-485 to Ethernet/WiFi converter.
65
65
  - [Requests and Responses](https://pyplumio.denpa.pro/protocol.html#requests-and-responses)
66
66
  - [Communication](https://pyplumio.denpa.pro/protocol.html#communication)
67
67
  - [Versioning](https://pyplumio.denpa.pro/protocol.html#versioning)
68
- - [Supported frames](https://pyplumio.denpa.pro/frames.html)
68
+ - [Supported Frames](https://pyplumio.denpa.pro/frames.html)
69
69
  - [CLI Parameter Mapper](https://pyplumio.denpa.pro/cli.html)
70
70
 
71
71
  ## Parameter Mapping CLI
@@ -38,7 +38,7 @@ through network by using RS-485 to Ethernet/WiFi converter.
38
38
  - [Requests and Responses](https://pyplumio.denpa.pro/protocol.html#requests-and-responses)
39
39
  - [Communication](https://pyplumio.denpa.pro/protocol.html#communication)
40
40
  - [Versioning](https://pyplumio.denpa.pro/protocol.html#versioning)
41
- - [Supported frames](https://pyplumio.denpa.pro/frames.html)
41
+ - [Supported Frames](https://pyplumio.denpa.pro/frames.html)
42
42
  - [CLI Parameter Mapper](https://pyplumio.denpa.pro/cli.html)
43
43
 
44
44
  ## Parameter Mapping CLI
@@ -83,6 +83,15 @@ this phase, a connection-lost error is reported instead. Once startup succeeds,
83
83
  the full-screen interface opens with the parameter table already filled and keeps
84
84
  polling in the background.
85
85
 
86
+ If ``<output>/pyplumio/parameters/custom/<model_slug>.py`` exists on disk with a
87
+ matching model and product ID, the CLI loads its mapped ``service_parameters``,
88
+ ``patches``, and comments automatically—taking precedence over bundled definitions in
89
+ PyPlumIO—and displays a confirmation notice in the status bar. If no local file exists,
90
+ bundled definitions for the detected model are loaded when available. If an existing
91
+ local file fails to load or has a mismatched model or product ID, a warning is displayed and the
92
+ CLI falls back to built-in definitions. See :doc:`custom_parameters` for details on
93
+ ``custom_parameters()`` definitions and model slugs.
94
+
86
95
  The interface consists of:
87
96
 
88
97
  - **Header**: Inverted top bar showing connected controller model, product ID, connection URL, and last update timestamp.
@@ -100,7 +109,7 @@ At the bottom of the screen, a wizard guides you through naming and configuring
100
109
  2. **Name**: Enter a unique snake_case name (e.g. ``heating_temp``):
101
110
  - Standard ecoMAX parameter names for the connected device are offered as autocompletion (substring match; names already used by other indices are left out).
102
111
  - 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.
112
+ - 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.
104
113
  - 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
114
  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
115
  4. **Number Settings**: If configuring a number (defaults come from the matched template or existing mapping, or fall back to ``0``, ``1``, and ``none``):
@@ -108,7 +117,7 @@ At the bottom of the screen, a wizard guides you through naming and configuring
108
117
  - **Step**: Multiplier/step (default: ``1``; e.g. ``1``, ``0.1``, ``10``).
109
118
  - **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
119
  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]``).
120
+ 6. **Confirm**: Confirm that the live preview matches your controller display (``[y/N]``).
112
121
  7. Press ``Esc`` at any point to cancel the wizard.
113
122
 
114
123
  Connection Resilience
@@ -118,9 +127,9 @@ If the serial connection or TCP bridge drops during a session, the CLI automatic
118
127
 
119
128
  .. code-block:: text
120
129
 
121
- Connection lost. Reconnecting in background in 20 seconds...
130
+ Connection lost. Reconnecting in background in 5 seconds...
122
131
 
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.
132
+ The CLI automatically retries the connection every 5 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
133
 
125
134
  Saving & Output Files
126
135
  ---------------------
@@ -140,7 +149,8 @@ The utility produces the following three files on disk (and inside ``<output>/<m
140
149
 
141
150
  1. **Custom Parameter Module**:
142
151
  ``<output>/pyplumio/parameters/custom/<model_slug>.py``
143
- Contains the ``CustomParameters`` class definition, model signature, and descriptions dictionary.
152
+ Contains the ``PARAMETERS = custom_parameters(...)`` definition with model,
153
+ product ID, and service parameters dictionary.
144
154
 
145
155
  2. **Test Module**:
146
156
  ``<output>/tests/parameters/custom/test_<model_slug>.py``
@@ -150,6 +160,10 @@ The utility produces the following three files on disk (and inside ``<output>/<m
150
160
  ``<output>/tests/testdata/parameters/<model_slug>.json``
151
161
  Raw frame capture used for reproducible testing.
152
162
 
163
+ Restarting the CLI with the same ``--output`` directory (or working directory)
164
+ automatically reloads these saved definitions whether running from source, an installed
165
+ package, or standalone ``pyplumio.exe``.
166
+
153
167
  Press ``Ctrl+Q`` to exit the application cleanly.
154
168
 
155
169
  Contributing Mapped Parameters
@@ -159,3 +173,7 @@ Once you have mapped parameters for your controller model:
159
173
 
160
174
  1. Open a pull request against `PyPlumIO <https://github.com/denpamusic/PyPlumIO/>`_ adding the generated files.
161
175
  2. Alternatively, create an issue on GitHub and attach the generated ``<model_slug>.zip`` archive (or the three generated files).
176
+
177
+ For hand-authoring ``patches``, factoring repeated descriptors with ``functools.partial``,
178
+ configuring ``number()`` / ``switch()`` options (such as ``precision`` or ``optimistic``),
179
+ and running all required pre-PR verification checks, see :doc:`custom_parameters`.
@@ -0,0 +1,195 @@
1
+ Custom Parameters
2
+ =================
3
+
4
+ Overview
5
+ --------
6
+
7
+ ecoMAX firmware varies across controller models: newer models store settings in
8
+ the service parameter table (:ref:`EcomaxServiceParameters<EcomaxServiceParameters>`),
9
+ and some models shift or repurpose entries in the standard parameter table
10
+ (:ref:`EcomaxParameters<EcomaxParameters>`). Custom parameter modules map those
11
+ entries to named parameters so they work seamlessly with :doc:`reading` and
12
+ :doc:`writing` (``ecomax.get(...)`` and ``ecomax.set(...)``).
13
+
14
+ A custom module defines one or both of the following tables:
15
+
16
+ .. list-table::
17
+ :widths: 24 76
18
+ :header-rows: 1
19
+
20
+ * - Table
21
+ - Purpose
22
+ * - ``service_parameters``
23
+ - Maps :ref:`EcomaxServiceParameters<EcomaxServiceParameters>` by index.
24
+ * - ``patches``
25
+ - Overrides :ref:`EcomaxParameters<EcomaxParameters>` by name.
26
+
27
+ To match a module to a controller, PyPlumIO converts
28
+ :py:class:`~pyplumio.structures.product_info.ProductInfo` ``model`` (from the
29
+ :ref:`UID<UID>` response) into ``<model_slug>`` by replacing ``"-"`` and
30
+ ``" "`` with ``"_"`` and lowercasing (for example, ``"ecoMAX 350P2-ZF"`` becomes
31
+ ``ecomax_350p2_zf``). **Both** the exact ``model`` string and numeric ``id``
32
+ (visible in the CLI header or via ``await ecomax.get("product")``) must match
33
+ the connected controller.
34
+
35
+ How-To Guides
36
+ -------------
37
+
38
+ Generating a Starter Module with the CLI
39
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40
+
41
+ Use the interactive utility in :doc:`cli` to connect to your controller, inspect
42
+ raw :ref:`EcomaxServiceParameters<EcomaxServiceParameters>` entries, and export
43
+ a starter ``service_parameters`` module, test file, and captured frame JSON
44
+ (optionally bundled as ``<model_slug>.zip``). Saving in the CLI regenerates
45
+ plain ``number()`` and ``switch()`` entries for ``service_parameters``, so add
46
+ manual ``patches`` or ``functools.partial`` helpers afterward.
47
+
48
+ Writing or Patching a Module by Hand
49
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
50
+
51
+ Create ``pyplumio/parameters/custom/<model_slug>.py`` with a module docstring,
52
+ ``from __future__ import annotations``, and a module-level
53
+ ``PARAMETERS = custom_parameters(...)`` constant. See
54
+ `ecomax_350p2_zf.py <https://github.com/denpamusic/PyPlumIO/blob/main/pyplumio/parameters/custom/ecomax_350p2_zf.py>`_
55
+ (``pyplumio/parameters/custom/ecomax_350p2_zf.py``) for a complete reference.
56
+
57
+ For ``service_parameters``, map each raw index to ``number()`` or ``switch()``,
58
+ use ``#`` comments to document enum-style numeric options, and factor repeated
59
+ descriptors with ``functools.partial``. When raw wire values are scaled or
60
+ shifted, PyPlumIO unpacks them as
61
+ ``unpacked = round((raw - offset) * step, precision)``:
62
+
63
+ - **Positive offset**: ``number("heating_curve_shift", offset=20, unit="°C")``
64
+ maps raw ``0..40`` to ``-20..20 °C``.
65
+ - **Negative offset with step**: ``partial(number, step=10.0, offset=-30, unit="rpm")``
66
+ maps raw ``0..255`` to ``300..2850 rpm``.
67
+
68
+ .. code-block:: python
69
+
70
+ """Contains custom parameters for ecoMAX 860P4-NM TOUCH."""
71
+
72
+ from __future__ import annotations
73
+
74
+ from functools import partial
75
+
76
+ from pyplumio.parameters.custom import custom_parameters, number, switch
77
+
78
+ _fan_speed = partial(number, step=10.0, offset=-30, unit="rpm")
79
+
80
+ PARAMETERS = custom_parameters(
81
+ model="ecoMAX 860P4-NM TOUCH",
82
+ id=41,
83
+ service_parameters={
84
+ 0: number("max_boiler_output", unit="kW"),
85
+ 11: _fan_speed("fan_speed_30"),
86
+ # 0 - off, 1 - priority, 2 - no priority.
87
+ 90: number("water_heater_pump_mode"),
88
+ 100: switch("heat_exchanger"),
89
+ 220: number("fuel_correction", offset=20, unit="%"),
90
+ },
91
+ )
92
+
93
+ For ``patches``, keys are the **original** standard parameter names from
94
+ :ref:`EcomaxParameters<EcomaxParameters>`, mapped to replacement ``number()`` or
95
+ ``switch()`` descriptors (adapted from
96
+ ``pyplumio/parameters/custom/ecomax_860d3_hb.py``):
97
+
98
+ .. code-block:: python
99
+
100
+ PARAMETERS = custom_parameters(
101
+ model="ecoMAX 860D3-HB",
102
+ id=48,
103
+ patches={
104
+ "disable_pump_on_thermostat": number("water_heater_target_temp", unit="°C"),
105
+ "pump_hysteresis": switch("water_heater_disinfection"),
106
+ },
107
+ )
108
+
109
+ Testing and Contributing
110
+ ~~~~~~~~~~~~~~~~~~~~~~~~
111
+
112
+ You can contribute mapped parameters in two ways:
113
+
114
+ 1. **GitHub Issue**: Attach the ``<model_slug>.zip`` archive exported by
115
+ :doc:`cli` to an issue on `PyPlumIO <https://github.com/denpamusic/PyPlumIO/>`_.
116
+ 2. **Pull Request**: Open a PR containing all three required files:
117
+
118
+ - ``pyplumio/parameters/custom/<model_slug>.py`` — exports ``PARAMETERS``
119
+ with ``model`` matching ``<model_slug>``, a non-bool integer ``id``, and
120
+ non-empty ``service_parameters`` or ``patches``.
121
+ - ``tests/testdata/parameters/<model_slug>.json`` — real frame data captured
122
+ from the controller.
123
+ - ``tests/parameters/custom/test_<model_slug>.py`` — parametrized tests
124
+ verifying each parameter's class, value, bounds, and unit; use
125
+ `test_ecomax_350p2_zf.py <https://github.com/denpamusic/PyPlumIO/blob/main/tests/parameters/custom/test_ecomax_350p2_zf.py>`_
126
+ (``service_parameters``) or
127
+ `test_ecomax_860d3_hb.py <https://github.com/denpamusic/PyPlumIO/blob/main/tests/parameters/custom/test_ecomax_860d3_hb.py>`_
128
+ (``patches``) as a template.
129
+
130
+ Before opening a PR, verify the test suite and linters pass locally:
131
+
132
+ .. code-block:: console
133
+
134
+ $ uv run pytest
135
+ $ prek run --all-files
136
+
137
+ DSL Reference
138
+ -------------
139
+
140
+ .. autofunction:: pyplumio.parameters.custom.custom_parameters
141
+
142
+ .. autofunction:: pyplumio.parameters.custom.number
143
+
144
+ .. autofunction:: pyplumio.parameters.custom.switch
145
+
146
+ Supported Units
147
+ ~~~~~~~~~~~~~~~
148
+
149
+ ``number(..., unit=...)`` accepts ``UnitOfMeasurement`` enum members,
150
+ ``PERCENTAGE``, ``None``, or any string literal listed below. Passing an
151
+ unrecognized string raises ``ValueError``.
152
+
153
+ .. list-table::
154
+ :widths: 20 35 45
155
+ :header-rows: 1
156
+
157
+ * - Literal
158
+ - ``UnitOfMeasurement`` / Constant
159
+ - Meaning
160
+ * - ``"°C"``
161
+ - ``CELSIUS``
162
+ - Degrees Celsius
163
+ * - ``"kW"``
164
+ - ``KILO_WATT``
165
+ - Kilowatts
166
+ * - ``"g"``
167
+ - ``GRAMS``
168
+ - Grams
169
+ * - ``"kg"``
170
+ - ``KILOGRAMS``
171
+ - Kilograms
172
+ * - ``"kWh/kg"``
173
+ - ``KILO_WATT_HOUR_PER_KILOGRAM``
174
+ - Kilowatt-hours per kilogram
175
+ * - ``"kg/h"``
176
+ - ``KILOGRAMS_PER_HOUR``
177
+ - Kilograms per hour
178
+ * - ``"s"``
179
+ - ``SECONDS``
180
+ - Seconds
181
+ * - ``"min"``
182
+ - ``MINUTES``
183
+ - Minutes
184
+ * - ``"days"``
185
+ - ``DAYS``
186
+ - Days
187
+ * - ``"Pa"``
188
+ - ``PASCAL``
189
+ - Pascals
190
+ * - ``"rpm"``
191
+ - ``REVOLUTIONS_PER_MINUTE``
192
+ - Revolutions per minute
193
+ * - ``"%"``
194
+ - ``PERCENTAGE``
195
+ - Percentage
@@ -113,7 +113,8 @@ changes.
113
113
  Parameters are represented in the same way as in :ref:`ecomaxparameters`.
114
114
  Raw parameters are available under the ``ecomax_service_parameters`` key.
115
115
  Parameters with known meaning are also available by name for verified
116
- products only.
116
+ products only; see :doc:`custom_parameters` for defining product-specific
117
+ ``service_parameters`` mappings and standard ``patches``.
117
118
 
118
119
  Request
119
120
  ^^^^^^^
@@ -794,5 +795,6 @@ Handlers
794
795
  ^^^^^^^^
795
796
 
796
797
  .. autoclass:: pyplumio.structures.frame_versions.FrameVersionsStructure
798
+ :no-index:
797
799
 
798
800
  .. autoclass:: pyplumio.structures.sensor_data.SensorDataStructure
@@ -53,6 +53,7 @@ Documentation
53
53
  callbacks
54
54
  mixers_thermostats
55
55
  schedules
56
+ custom_parameters
56
57
  protocol
57
58
  frames
58
59
  cli
@@ -3,10 +3,11 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import argparse
6
+ import asyncio
6
7
  from collections.abc import Iterator, Sequence
7
8
  from contextlib import contextmanager, suppress
8
9
  from enum import StrEnum, unique
9
- import inspect
10
+ import importlib.util
10
11
  import logging
11
12
  from pathlib import Path
12
13
  import sys
@@ -27,9 +28,13 @@ from pyplumio.exceptions import PyPlumIOError
27
28
  from pyplumio.parameters import ParameterValues
28
29
  from pyplumio.parameters.custom import (
29
30
  CustomParameters,
31
+ extract_custom_parameters,
30
32
  load_custom_parameters,
31
33
  model_slug,
32
34
  )
35
+ from pyplumio.structures.product_info import ProductInfo
36
+
37
+ _LOGGER = logging.getLogger(__name__)
33
38
 
34
39
 
35
40
  @unique
@@ -114,22 +119,75 @@ def _write_status(message: str) -> None:
114
119
 
115
120
 
116
121
  def _load_comments(
117
- custom_parameters: CustomParameters, output_dir: Path, slug: str
122
+ custom_parameters: CustomParameters,
123
+ output_dir: Path,
124
+ slug: str,
125
+ *,
126
+ prefer_output: bool = True,
118
127
  ) -> dict[int, str]:
119
128
  """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)
129
+ path = custom_module_path(output_dir, slug) if prefer_output else None
130
+ if path is None or not path.is_file():
131
+ path = custom_parameters.source
125
132
 
126
- if path.is_file():
133
+ if path is not None and path.is_file():
127
134
  with suppress(OSError):
128
135
  return extract_comments(path.read_text(encoding="utf-8"))
129
136
 
130
137
  return {}
131
138
 
132
139
 
140
+ def _load_custom_parameters_from_file(
141
+ path: Path, product_info: ProductInfo
142
+ ) -> CustomParameters:
143
+ """Load and validate custom parameters from a module file on disk."""
144
+ slug = model_slug(product_info.model)
145
+ spec = importlib.util.spec_from_file_location(f"_pyplumio_cli_custom_{slug}", path)
146
+ if spec is None or spec.loader is None:
147
+ raise ImportError(f"Could not create module spec for {path}")
148
+
149
+ module = importlib.util.module_from_spec(spec)
150
+ spec.loader.exec_module(module)
151
+ instance = extract_custom_parameters(module, path=path)
152
+ if instance is None:
153
+ raise ValueError(f"No CustomParameters instance found in {path.name}")
154
+
155
+ if not instance.validate(product_info):
156
+ raise ValueError(
157
+ f"Model or product ID mismatch in {path.name} "
158
+ f"(expected {product_info.model!r} ID {product_info.id})"
159
+ )
160
+
161
+ return instance
162
+
163
+
164
+ async def _load_cli_custom_parameters(
165
+ output_dir: Path, product_info: ProductInfo
166
+ ) -> tuple[CustomParameters | None, str, bool]:
167
+ """Load custom parameters from output directory or installed package."""
168
+ path = custom_module_path(output_dir, model_slug(product_info.model))
169
+ if path.is_file():
170
+ try:
171
+ custom_parameters = await asyncio.to_thread(
172
+ _load_custom_parameters_from_file, path, product_info
173
+ )
174
+ except Exception as err:
175
+ message = (
176
+ f"Failed to load custom parameters from {path}: "
177
+ f"{_format_error(err)}. Falling back to built-in definitions."
178
+ )
179
+ _LOGGER.warning("%s", message)
180
+ warning = f"Warning: {message}"
181
+ _write_status(warning)
182
+ return await load_custom_parameters(product_info), warning, False
183
+
184
+ notice = f"Loaded custom parameters from {output_dir}."
185
+ _write_status(notice)
186
+ return custom_parameters, notice, True
187
+
188
+ return await load_custom_parameters(product_info), "", False
189
+
190
+
133
191
  async def prompt_connection_url(
134
192
  session: PromptSession[str] | None = None,
135
193
  ) -> str:
@@ -182,18 +240,29 @@ async def run_app(args: argparse.Namespace) -> int:
182
240
  )
183
241
  try:
184
242
  product_info = await session.connect()
185
- if custom_parameters := await load_custom_parameters(product_info):
243
+ (
244
+ custom_parameters,
245
+ startup_status,
246
+ from_output,
247
+ ) = await _load_cli_custom_parameters(output_dir, product_info)
248
+ if custom_parameters:
186
249
  comments = _load_comments(
187
- custom_parameters, output_dir, model_slug(product_info.model)
250
+ custom_parameters,
251
+ output_dir,
252
+ model_slug(product_info.model),
253
+ prefer_output=from_output,
188
254
  )
189
- for index, description in custom_parameters.descriptions.items():
255
+ for index, description in custom_parameters.service_parameters.items():
190
256
  table.set_description(
191
257
  index, description, comment=comments.get(index, "")
192
258
  )
193
259
 
194
- table.overrides = tuple(custom_parameters.overrides)
260
+ table.patches = dict(custom_parameters.patches)
195
261
 
196
262
  app, state = create_app(session, table, output_dir, zip_output=args.zip)
263
+ if startup_status:
264
+ state.status = startup_status
265
+
197
266
  with _capture_logs(state):
198
267
  _write_status("Starting interface...")
199
268
  await app.run_async()