deploy: a4fcd70

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: e4a11425e167253d86bdc270a516ce5b
+tags: 645f666f9bcd5a90fca523b33c5a78b7

CNAME

@@ -0,0 +1 @@
+pyplumio.denpa.pro

_sources/index.rst

@@ -0,0 +1,51 @@
+.. PyPlumIO documentation master file, created by
+   sphinx-quickstart on Mon Feb 13 10:56:31 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to PyPlumIO's documentation!
+====================================
+
+This project aims to provide complete and easy to use solution for communicating with
+climate devices by `Plum Sp. z o.o. <https://www.plum.pl/>`_
+
+Currently it supports reading and writing parameters of ecoMAX controllers by
+Plum Sp. z o.o., getting service password and sending network information to
+show on controller's display.
+
+Devices can be connected directly via RS-485 to USB adapter or through network by using
+RS-485 to Ethernet/WiFi converter.
+
+Quickstart
+==========
+1. To use PyPlumIO, first install it using pip:
+
+.. code-block:: console
+
+    (.venv) $ pip install pyplumio
+
+2. Connect to the ecoMAX controller:
+
+>>> connection = pyplumio.open_serial_connection("/dev/ttyUSB0")
+>>> await connection.connect()
+>>> ecomax = await connection.get("ecomax")
+
+3. Print some values:
+
+>>> print(await ecomax.get("heating_temp"))
+
+4. Don't forget to close the connection:
+
+>>> await connection.close()
+
+Documentation
+=============
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   usage
+   protocol
+
+.. autosummary::
+   :toctree: _autosummary

_sources/protocol.rst

@@ -0,0 +1,116 @@
+Protocol
+========
+Plum devices use RS-485 standard for communication.
+
+Each frame consists of header (7 bytes), message type (1 byte),
+message data (optional), CRC (1 byte) and frame end delimiter (1 byte).
+The minimum frame size therefore is 10 bytes.
+
+Protocol supports unicast and broadcast frames.
+Broadcast frames will always have their recipient address set
+to **0x00**, while unicast messages will have specific device address.
+ecoMAX controller address is **0x45**, ecoSTER panel
+address is **0x51**.
+
+Frame structure
+---------------
+
+* Header:
+    * [Byte] Frame start delimiter. Always **0x68**.
+    * [Unsigned Short] Byte size of the frame. Includes CRC and frame end delimiter. 
+    * [Byte] Recipient address.
+    * [Byte] Sender address.
+    * [Byte] Sender type. PyPlumIO uses EcoNET type **48**.
+    * [Byte] ecoNET version. PyPlumIO uses version **5**.
+* Body:
+    * [Byte] Frame type.
+    * [Byte*] Message data (optional).
+    * [Byte] Frame CRC.
+    * [Byte] Frame end delimiter. Always **0x16**.
+
+Requests and Responses
+----------------------
+For example, we can request list of editable parameters from the ecoMAX
+controller by sending frame with frame type **49** and receive response
+with frame type **177** that contains requested parameters.
+
+Communication
+-------------
+The controller constantly sends ``ProgramVersionRequest[type=64]`` and
+``CheckDeviceRequest[type=48]`` requests to every known device on the
+network and broadcasts ``RegulatorDataMessage[type=8]`` message,
+that contains basic controller data.
+
+Initial exchange between ecoMAX controller (EM) and
+PyPlumIO library (PIO) can be illustrated with following diagram:
+
++----------+---+-----------+-------------------------+-------------------------------+
+| Sender   |   | Receiver  | Frame                   | Description                   |
++==========+===+===========+=========================+===============================+
+| EM[0x45] | > | ANY[0x00] | RegulatorDataMessage    | Contains ecoMAX data.         |
++----------+---+-----------+-------------------------+-------------------------------+
+| EM[0x45] | > | PIO[0x56] | ProgramVersionRequest   | Program version request.      |
++----------+---+-----------+-------------------------+-------------------------------+ 
+| EM[0x45] | < | PIO[0x56] | ProgramVersionResponse  | Contains program version.     |
++----------+---+-----------+-------------------------+-------------------------------+
+| EM[0x45] | > | PIO[0x56] | CheckDeviceRequest      | Check device request.         |
++----------+---+-----------+-------------------------+-------------------------------+
+| EM[0x45] | < | PIO[0x56] | DeviceAvailableResponse | Contains network information. |
++----------+---+-----------+-------------------------+-------------------------------+
+| EM[0x45] | > | PIO[0x56] | SensorDataMessage       | Contains ecoMAX sensor data.  |
++----------+---+-----------+-------------------------+-------------------------------+
+
+.. note::
+
+    Device network address is listed in square brackets.
+
+Versioning
+----------
+
+Protocol has built-in way to track frame versions. This is used to
+synchronize changes between devices.
+
+Both broadcast ``RegulatorDataMessage[type=8]`` and unicast
+``SensorDataMessage[type=53]`` frames sent by the ecoMAX controller
+contain versioning data.
+
+This data can be represented with following dictionary:
+
+.. code-block:: python
+
+    frame_versions: dict[int, int] = {
+        49: 37,
+        50: 37,
+        54: 1,
+        56: 5,
+        57: 1,
+        61: 40767,
+        80: 1,
+        81: 1,
+        82: 1,
+        83: 1,
+    }
+
+
+In this dictionary, keys are frame types and values are version numbers.
+
+In example above, frame ``ParametersRequest[type=49]`` has version 37.
+If we change any parameters either remotely or on the controller itself,
+the version number will increase, so PyPlumIO will be able
+to tell that it's need to request list of parameters again
+to obtain changes.
+
+.. code-block:: python
+
+    frame_versions: dict[int, int] = {
+        49: 38,  # Note the version number change.
+        50: 37,
+        54: 1,
+        56: 5,
+        57: 1,
+        61: 40767,
+        80: 1,
+        81: 1,
+        82: 1,
+        83: 1,
+    }