You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@plc4x.apache.org by hu...@apache.org on 2024/02/21 04:52:24 UTC

(plc4x) branch fix/plc4py/documentation updated: fix(plc4py): Add write support to the api

This is an automated email from the ASF dual-hosted git repository.

hutcheb pushed a commit to branch fix/plc4py/documentation
in repository https://gitbox.apache.org/repos/asf/plc4x.git


The following commit(s) were added to refs/heads/fix/plc4py/documentation by this push:
     new 2abc6c39a1 fix(plc4py): Add write support to the api
2abc6c39a1 is described below

commit 2abc6c39a125a0c5196ffcdc425d789dc3435080
Author: Ben Hutcheson <be...@gmail.com>
AuthorDate: Wed Feb 21 05:52:14 2024 +0100

    fix(plc4py): Add write support to the api
---
 sandbox/plc4py/plc4py/api/PlcConnection.py         |  4 +--
 sandbox/plc4py/plc4py/api/messages/PlcRequest.py   | 22 +++++++++++-
 sandbox/plc4py/plc4py/api/messages/PlcResponse.py  |  7 ++++
 .../plc4py/plc4py/drivers/mock/MockConnection.py   | 39 ++++++++++++++++++----
 .../plc4py/drivers/modbus/ModbusConnection.py      | 36 +++++++++++++++++---
 .../plc4py/plc4py/drivers/modbus/ModbusDevice.py   | 16 +++++++--
 .../plc4py/plc4py/drivers/umas/UmasConnection.py   | 27 ++++++++++++++-
 sandbox/plc4py/plc4py/drivers/umas/UmasDevice.py   | 26 ++++++++++++---
 sandbox/plc4py/plc4py/spi/messages/PlcRequest.py   | 21 ++++++++++++
 .../spi/messages/PlcWriter.py}                     | 30 ++++++++---------
 sandbox/plc4py/pytest.ini                          |  2 ++
 .../tests/unit/plc4py/api/test_PlcRequest.py       | 14 ++++----
 .../drivers/modbus/test_modbus_connection.py       | 29 ++++++++++++++--
 .../asciidoc/users/getting-started/plc4py.adoc     | 12 ++-----
 14 files changed, 226 insertions(+), 59 deletions(-)

diff --git a/sandbox/plc4py/plc4py/api/PlcConnection.py b/sandbox/plc4py/plc4py/api/PlcConnection.py
index 7a2da9c3da..3d4187169b 100644
--- a/sandbox/plc4py/plc4py/api/PlcConnection.py
+++ b/sandbox/plc4py/plc4py/api/PlcConnection.py
@@ -20,7 +20,7 @@ import asyncio
 from abc import abstractmethod
 from typing import Awaitable
 
-from plc4py.api.messages.PlcResponse import PlcResponse, PlcReadResponse
+from plc4py.api.messages.PlcResponse import PlcResponse, PlcTagResponse, PlcReadResponse
 from plc4py.api.messages.PlcRequest import ReadRequestBuilder, PlcRequest
 from plc4py.api.value.PlcValue import PlcResponseCode
 from plc4py.spi.configuration.PlcConfiguration import PlcConfiguration
@@ -63,7 +63,7 @@ class PlcConnection(GenericGenerator):
         """
         pass
 
-    def _default_failed_request(
+    def _default_failed_read_request(
         self, code: PlcResponseCode
     ) -> Awaitable[PlcReadResponse]:
         """
diff --git a/sandbox/plc4py/plc4py/api/messages/PlcRequest.py b/sandbox/plc4py/plc4py/api/messages/PlcRequest.py
index e913d8255d..947cc31142 100644
--- a/sandbox/plc4py/plc4py/api/messages/PlcRequest.py
+++ b/sandbox/plc4py/plc4py/api/messages/PlcRequest.py
@@ -23,6 +23,7 @@ from typing import Union, List, Dict
 
 from plc4py.api.messages.PlcField import PlcTag
 from plc4py.api.messages.PlcMessage import PlcMessage
+from plc4py.api.value.PlcValue import PlcValue
 from plc4py.utils.GenericTypes import GenericGenerator
 
 
@@ -53,10 +54,19 @@ class PlcQueryRequest(PlcRequest):
 @dataclass
 class PlcReadRequest(PlcTagRequest):
     """
-    Base type for all messages sent from the plc4x system to a connected plc.
+    Base type for all read messages sent from the plc4x system to a connected plc.
     """
 
 
+@dataclass
+class PlcWriteRequest(PlcTagRequest):
+    """
+    Base type for all write messages sent from the plc4x system to a connected plc.
+    """
+
+    values: Dict[str, PlcValue] = field(default_factory=lambda: OrderedDict())
+
+
 @dataclass
 class PlcBrowseRequest(PlcQueryRequest):
     """
@@ -74,6 +84,16 @@ class ReadRequestBuilder(GenericGenerator):
         pass
 
 
+class WriteRequestBuilder(GenericGenerator):
+    @abstractmethod
+    def build(self) -> PlcWriteRequest:
+        pass
+
+    @abstractmethod
+    def add_item(self, tag_name: str, address_string: str, value: PlcValue) -> None:
+        pass
+
+
 class BrowseRequestBuilder(GenericGenerator):
     @abstractmethod
     def build(self) -> PlcBrowseRequest:
diff --git a/sandbox/plc4py/plc4py/api/messages/PlcResponse.py b/sandbox/plc4py/plc4py/api/messages/PlcResponse.py
index 115b8573a0..33d726aa0a 100644
--- a/sandbox/plc4py/plc4py/api/messages/PlcResponse.py
+++ b/sandbox/plc4py/plc4py/api/messages/PlcResponse.py
@@ -66,6 +66,13 @@ class PlcReadResponse(PlcTagResponse):
         return cast(int, self.tags[name].value.value)
 
 
+@dataclass
+class PlcWriteResponse(PlcTagResponse):
+    """
+    Response to a {@link PlcWriteRequest}.
+    """
+
+
 @dataclass
 class PlcQueryResponse(PlcResponse):
     tags: Dict[str, List[ResponseItem[PlcTag]]]
diff --git a/sandbox/plc4py/plc4py/drivers/mock/MockConnection.py b/sandbox/plc4py/plc4py/drivers/mock/MockConnection.py
index 9b6b1644c0..64e9bdd00f 100644
--- a/sandbox/plc4py/plc4py/drivers/mock/MockConnection.py
+++ b/sandbox/plc4py/plc4py/drivers/mock/MockConnection.py
@@ -22,13 +22,15 @@ import logging
 from dataclasses import dataclass, field
 from typing import Awaitable, Type, List, Dict
 
+from plc4py.spi.messages.PlcWriter import PlcWriter
+
 from plc4py.drivers.mock import MockTag
 from plc4py.drivers.mock.MockTag import MockTagBuilder
 from plc4py.spi.messages.PlcRequest import DefaultReadRequestBuilder
 
 import plc4py
 
-from plc4py.api.PlcConnection import PlcConnection
+from plc4py.api.PlcConnection import PlcConnection, PlcConnectionMetaData
 from plc4py.api.PlcDriver import PlcDriver
 from plc4py.api.authentication.PlcAuthentication import PlcAuthentication
 from plc4py.api.exceptions.exceptions import PlcFieldParseException
@@ -36,9 +38,9 @@ from plc4py.api.messages.PlcField import PlcTag
 from plc4py.api.messages.PlcRequest import (
     ReadRequestBuilder,
     PlcReadRequest,
-    PlcRequest,
+    PlcRequest, PlcWriteRequest,
 )
-from plc4py.api.messages.PlcResponse import PlcReadResponse, PlcResponse
+from plc4py.api.messages.PlcResponse import PlcReadResponse, PlcResponse, PlcWriteResponse
 from plc4py.api.value.PlcValue import PlcResponseCode, PlcValue
 from plc4py.drivers.PlcDriverLoader import PlcDriverLoader
 from plc4py.spi.messages.PlcReader import PlcReader
@@ -49,22 +51,22 @@ from plc4py.spi.values.PlcValues import PlcINT
 
 @dataclass
 class MockDevice:
-    def read(self, tag: MockTag) -> List[ResponseItem[PlcValue]]:
+    def read(self, tag: MockTag) -> ResponseItem[PlcValue]:
         """
         Reads one field from the Mock Device
         """
         logging.debug(f"Reading field {str(tag)} from Mock Device")
 
         if tag.data_type == "BOOL":
-            return [ResponseItem(PlcResponseCode.OK, PlcBOOL(False))]
+            return ResponseItem(PlcResponseCode.OK, PlcBOOL(False))
         elif tag.data_type == "INT":
-            return [ResponseItem(PlcResponseCode.OK, PlcINT(0))]
+            return ResponseItem(PlcResponseCode.OK, PlcINT(0))
         else:
             raise PlcFieldParseException
 
 
 @dataclass
-class MockConnection(PlcConnection, PlcReader):
+class MockConnection(PlcConnection, PlcReader, PlcWriter, PlcConnectionMetaData):
     _is_connected: bool = False
     device: MockDevice = field(default_factory=lambda: MockDevice())
 
@@ -139,6 +141,29 @@ class MockConnection(PlcConnection, PlcReader):
         future = asyncio.ensure_future(_request(request, self.device))
         return future
 
+    def _write(self, request: PlcWriteRequest) -> Awaitable[PlcWriteResponse]:
+        """
+        Executes a PlcReadRequest
+        """
+        if self.device is None:
+            logging.error("No device is set in the mock connection!")
+            return self._default_failed_request(PlcResponseCode.NOT_CONNECTED)
+
+        async def _request(req, device) -> PlcReadResponse:
+            try:
+                response = PlcReadResponse(
+                    PlcResponseCode.OK,
+                    {tag_name: device.read(tag) for tag_name, tag in req.tags.items()},
+                )
+                return response
+            except Exception as e:
+                # TODO:- This exception is very general and probably should be replaced
+                return PlcReadResponse(PlcResponseCode.INTERNAL_ERROR, req.tags, {})
+
+        logging.debug("Sending read request to MockDevice")
+        future = asyncio.ensure_future(_request(request, self.device))
+        return future
+
 
 class MockDriver(PlcDriver):
     def __init__(self):
diff --git a/sandbox/plc4py/plc4py/drivers/modbus/ModbusConnection.py b/sandbox/plc4py/plc4py/drivers/modbus/ModbusConnection.py
index dd1060a27a..491ded41a1 100644
--- a/sandbox/plc4py/plc4py/drivers/modbus/ModbusConnection.py
+++ b/sandbox/plc4py/plc4py/drivers/modbus/ModbusConnection.py
@@ -24,11 +24,17 @@ import plc4py
 from plc4py.api.PlcConnection import PlcConnection, PlcConnectionMetaData
 from plc4py.api.PlcDriver import PlcDriver
 from plc4py.api.authentication.PlcAuthentication import PlcAuthentication
-from plc4py.api.messages.PlcResponse import PlcResponse, PlcReadResponse
+from plc4py.api.messages.PlcResponse import (
+    PlcResponse,
+    PlcReadResponse,
+    PlcWriteResponse,
+    PlcTagResponse,
+)
 from plc4py.api.messages.PlcRequest import (
     ReadRequestBuilder,
     PlcRequest,
     PlcReadRequest,
+    PlcWriteRequest,
 )
 from plc4py.api.value.PlcValue import PlcResponseCode
 from plc4py.drivers.PlcDriverLoader import PlcDriverLoader
@@ -36,12 +42,14 @@ from plc4py.drivers.modbus.ModbusConfiguration import ModbusConfiguration
 from plc4py.drivers.modbus.ModbusDevice import ModbusDevice
 from plc4py.drivers.modbus.ModbusProtocol import ModbusProtocol
 from plc4py.drivers.modbus.ModbusTag import ModbusTagBuilder
+from plc4py.spi.messages.PlcReader import PlcReader
 from plc4py.spi.messages.PlcRequest import DefaultReadRequestBuilder
+from plc4py.spi.messages.PlcWriter import PlcWriter
 from plc4py.spi.transport.Plc4xBaseTransport import Plc4xBaseTransport
 from plc4py.spi.transport.TCPTransport import TCPTransport
 
 
-class ModbusConnection(PlcConnection, PlcConnectionMetaData):
+class ModbusConnection(PlcConnection, PlcReader, PlcWriter, PlcConnectionMetaData):
     """
     Modbus TCP PLC connection implementation
     """
@@ -118,7 +126,7 @@ class ModbusConnection(PlcConnection, PlcConnectionMetaData):
         """
         if self._device is None:
             logging.error("No device is set in the modbus connection!")
-            return self._default_failed_request(PlcResponseCode.NOT_CONNECTED)
+            return self._default_failed_read_request(PlcResponseCode.NOT_CONNECTED)
 
         async def _request(req, device) -> PlcReadResponse:
             try:
@@ -132,6 +140,26 @@ class ModbusConnection(PlcConnection, PlcConnectionMetaData):
         future = asyncio.ensure_future(_request(request, self._device))
         return future
 
+    def _write(self, request: PlcWriteRequest) -> Awaitable[PlcTagResponse]:
+        """
+        Executes a PlcWriteRequest
+        """
+        if self._device is None:
+            logging.error("No device is set in the modbus connection!")
+            return self._default_failed_write_request(PlcResponseCode.NOT_CONNECTED)
+
+        async def _request(req, device) -> PlcWriteResponse:
+            try:
+                response = await asyncio.wait_for(device.write(req, self._transport), 5)
+                return response
+            except Exception as e:
+                # TODO:- This exception is very general and probably should be replaced
+                return PlcWriteResponse(PlcResponseCode.INTERNAL_ERROR, {})
+
+        logging.debug("Sending write request to ModbusDevice")
+        future = asyncio.ensure_future(_request(request, self._device))
+        return future
+
     def is_read_supported(self) -> bool:
         """
         Indicates if the connection supports read requests.
@@ -144,7 +172,7 @@ class ModbusConnection(PlcConnection, PlcConnectionMetaData):
         Indicates if the connection supports write requests.
         :return: True if connection supports writing, False otherwise
         """
-        return False
+        return True
 
     def is_subscribe_supported(self) -> bool:
         """
diff --git a/sandbox/plc4py/plc4py/drivers/modbus/ModbusDevice.py b/sandbox/plc4py/plc4py/drivers/modbus/ModbusDevice.py
index 5b06e6e717..977b9287e1 100644
--- a/sandbox/plc4py/plc4py/drivers/modbus/ModbusDevice.py
+++ b/sandbox/plc4py/plc4py/drivers/modbus/ModbusDevice.py
@@ -48,8 +48,8 @@ from plc4py.protocols.modbus.readwrite.ModbusPDUReadInputRegistersRequest import
 )
 from plc4py.spi.generation.WriteBuffer import WriteBufferByteBased
 
-from plc4py.api.messages.PlcRequest import PlcReadRequest
-from plc4py.api.messages.PlcResponse import PlcReadResponse
+from plc4py.api.messages.PlcRequest import PlcReadRequest, PlcWriteRequest
+from plc4py.api.messages.PlcResponse import PlcReadResponse, PlcWriteResponse
 from plc4py.api.value.PlcValue import PlcValue, PlcResponseCode
 from plc4py.protocols.modbus.readwrite.ModbusPDUReadHoldingRegistersRequest import (
     ModbusPDUReadHoldingRegistersRequest,
@@ -121,7 +121,9 @@ class ModbusDevice:
         result = message_future.result()
 
         if isinstance(result, ModbusPDUError):
-            response_item = ResponseItem(PlcResponseCode.ACCESS_DENIED, PlcNull(result.exception_code))
+            response_item = ResponseItem(
+                PlcResponseCode.ACCESS_DENIED, PlcNull(result.exception_code)
+            )
 
             response = PlcReadResponse(
                 PlcResponseCode.OK, {request.tag_names[0]: response_item}
@@ -149,3 +151,11 @@ class ModbusDevice:
             PlcResponseCode.OK, {request.tag_names[0]: response_item}
         )
         return response
+
+    async def write(
+        self, request: PlcWriteRequest, transport: Transport
+    ) -> PlcWriteResponse:
+        """
+        Writes one field from the Modbus Device
+        """
+        pass
diff --git a/sandbox/plc4py/plc4py/drivers/umas/UmasConnection.py b/sandbox/plc4py/plc4py/drivers/umas/UmasConnection.py
index 08f87b36fb..a81878e016 100644
--- a/sandbox/plc4py/plc4py/drivers/umas/UmasConnection.py
+++ b/sandbox/plc4py/plc4py/drivers/umas/UmasConnection.py
@@ -29,6 +29,8 @@ from plc4py.api.messages.PlcResponse import (
     PlcResponse,
     PlcReadResponse,
     PlcBrowseResponse,
+    PlcTagResponse,
+    PlcWriteResponse,
 )
 from plc4py.api.messages.PlcRequest import (
     ReadRequestBuilder,
@@ -36,6 +38,7 @@ from plc4py.api.messages.PlcRequest import (
     PlcReadRequest,
     BrowseRequestBuilder,
     PlcBrowseRequest,
+    PlcWriteRequest,
 )
 from plc4py.api.value.PlcValue import PlcResponseCode
 from plc4py.drivers.PlcDriverLoader import PlcDriverLoader
@@ -43,15 +46,17 @@ from plc4py.drivers.umas.UmasConfiguration import UmasConfiguration
 from plc4py.drivers.umas.UmasDevice import UmasDevice
 from plc4py.drivers.umas.UmasProtocol import UmasProtocol
 from plc4py.drivers.umas.UmasTag import UmasTagBuilder
+from plc4py.spi.messages.PlcReader import PlcReader
 from plc4py.spi.messages.PlcRequest import (
     DefaultReadRequestBuilder,
     DefaultBrowseRequestBuilder,
 )
+from plc4py.spi.messages.PlcWriter import PlcWriter
 from plc4py.spi.transport.Plc4xBaseTransport import Plc4xBaseTransport
 from plc4py.spi.transport.TCPTransport import TCPTransport
 
 
-class UmasConnection(PlcConnection, PlcConnectionMetaData):
+class UmasConnection(PlcConnection, PlcReader, PlcWriter, PlcConnectionMetaData):
     """
     Umas TCP PLC connection implementation
     """
@@ -177,6 +182,26 @@ class UmasConnection(PlcConnection, PlcConnectionMetaData):
         future = asyncio.ensure_future(_request(request, self._device))
         return future
 
+    def _write(self, request: PlcWriteRequest) -> Awaitable[PlcTagResponse]:
+        """
+        Executes a PlcWriteRequest
+        """
+        if self._device is None:
+            logging.error("No device is set in the umas connection!")
+            return self._default_failed_request(PlcResponseCode.NOT_CONNECTED)
+
+        async def _request(req, device) -> PlcWriteResponse:
+            try:
+                response = await asyncio.wait_for(device.write(req, self._transport), 5)
+                return response
+            except Exception as e:
+                # TODO:- This exception is very general and probably should be replaced
+                return PlcWriteResponse(PlcResponseCode.INTERNAL_ERROR, {})
+
+        logging.debug("Sending write request to ModbusDevice")
+        future = asyncio.ensure_future(_request(request, self._device))
+        return future
+
     def _browse(self, request: PlcBrowseRequest) -> Awaitable[PlcBrowseResponse]:
         """
         Executes a PlcBrowseRequest
diff --git a/sandbox/plc4py/plc4py/drivers/umas/UmasDevice.py b/sandbox/plc4py/plc4py/drivers/umas/UmasDevice.py
index b0e80efb2d..5326ea7a4b 100644
--- a/sandbox/plc4py/plc4py/drivers/umas/UmasDevice.py
+++ b/sandbox/plc4py/plc4py/drivers/umas/UmasDevice.py
@@ -23,8 +23,16 @@ from typing import Dict, List, Tuple, cast
 
 from plc4py.protocols.umas.readwrite.UmasUDTDefinition import UmasUDTDefinition
 
-from plc4py.api.messages.PlcRequest import PlcReadRequest, PlcBrowseRequest
-from plc4py.api.messages.PlcResponse import PlcReadResponse, PlcBrowseResponse
+from plc4py.api.messages.PlcRequest import (
+    PlcReadRequest,
+    PlcBrowseRequest,
+    PlcWriteRequest,
+)
+from plc4py.api.messages.PlcResponse import (
+    PlcReadResponse,
+    PlcBrowseResponse,
+    PlcWriteResponse,
+)
 from plc4py.api.value.PlcValue import PlcValue, PlcResponseCode
 from plc4py.drivers.umas.UmasConfiguration import UmasConfiguration
 from plc4py.drivers.umas.UmasTag import UmasTag
@@ -373,9 +381,9 @@ class UmasDevice:
                 quantity = 1
 
             response_item = ResponseItem(
-                    PlcResponseCode.OK,
-                    DataItem.static_parse(read_buffer, request_tag.data_type, quantity),
-                )
+                PlcResponseCode.OK,
+                DataItem.static_parse(read_buffer, request_tag.data_type, quantity),
+            )
 
             values[key] = response_item
 
@@ -432,6 +440,14 @@ class UmasDevice:
             response.values = {**response.values, **response_chunk.values}
         return response
 
+    async def write(
+        self, request: PlcWriteRequest, transport: Transport
+    ) -> PlcWriteResponse:
+        """
+        Writes one field from the UMAS Device
+        """
+        pass
+
     async def browse(
         self, request: PlcBrowseRequest, transport: Transport
     ) -> PlcBrowseResponse:
diff --git a/sandbox/plc4py/plc4py/spi/messages/PlcRequest.py b/sandbox/plc4py/plc4py/spi/messages/PlcRequest.py
index 1b11171ecb..f2eb5a48db 100644
--- a/sandbox/plc4py/plc4py/spi/messages/PlcRequest.py
+++ b/sandbox/plc4py/plc4py/spi/messages/PlcRequest.py
@@ -22,7 +22,10 @@ from plc4py.api.messages.PlcRequest import (
     ReadRequestBuilder,
     BrowseRequestBuilder,
     PlcBrowseRequest,
+    WriteRequestBuilder,
+    PlcWriteRequest,
 )
+from plc4py.api.value.PlcValue import PlcValue
 
 
 class TagBuilder:
@@ -48,6 +51,24 @@ class DefaultReadRequestBuilder(ReadRequestBuilder):
         self.read_request.tags[tag_name] = tag
 
 
+class DefaultWriteRequestBuilder(WriteRequestBuilder):
+    def __init__(self, tag_builder: TagBuilder):
+        super().__init__()
+        self.write_request = PlcWriteRequest()
+        self.tag_builder = tag_builder
+
+    def build(self) -> PlcWriteRequest:
+        return self.write_request
+
+    def add_item(self, tag_name: str, address_string: str, value: PlcValue) -> None:
+        tag = self.tag_builder.create(address_string)
+        self.write_request.tags[tag_name] = tag
+        self.write_request.values[tag_name] = value
+
+    def add_tag(self, tag_name: str, tag: PlcTag, value: PlcValue) -> None:
+        self.write_request.tags[tag_name] = tag
+
+
 class DefaultBrowseRequestBuilder(BrowseRequestBuilder):
     def __init__(self):
         super().__init__()
diff --git a/sandbox/plc4py/tests/unit/plc4py/drivers/modbus/test_modbus_connection.py b/sandbox/plc4py/plc4py/spi/messages/PlcWriter.py
similarity index 51%
copy from sandbox/plc4py/tests/unit/plc4py/drivers/modbus/test_modbus_connection.py
copy to sandbox/plc4py/plc4py/spi/messages/PlcWriter.py
index ac42a830fb..a4186beb6f 100644
--- a/sandbox/plc4py/tests/unit/plc4py/drivers/modbus/test_modbus_connection.py
+++ b/sandbox/plc4py/plc4py/spi/messages/PlcWriter.py
@@ -16,26 +16,22 @@
 # specific language governing permissions and limitations
 # under the License.
 #
-import time
 
-from plc4py.PlcDriverManager import PlcDriverManager
+from typing import Awaitable
 
+from plc4py.api.messages.PlcRequest import PlcWriteRequest
+from plc4py.api.messages.PlcResponse import PlcWriteResponse
 
-async def manual_test_plc_driver_modbus_connect():
-    driver_manager = PlcDriverManager()
-    async with driver_manager.connection("modbus://127.0.0.1:5555") as connection:
-        assert connection.is_connected()
-    assert not connection.is_connected()
 
+class PlcWriter:
+    """
+    Interface implemented by all PlcConnections that are able to write from remote resources.
+    """
 
-async def manual_test_plc_driver_modbus_read():
-    driver_manager = PlcDriverManager()
-    async with driver_manager.connection("modbus://192.168.1.174:502") as connection:
-        with connection.read_request_builder() as builder:
-            builder.add_item("Random Tag", "4x00001[10]")
-            request = builder.build()
+    def _write(self, request: PlcWriteRequest) -> Awaitable[PlcWriteResponse]:
+        """
+        Writes a requested value to a PLC
 
-        future = connection.execute(request)
-        await future
-        response = future.result()
-    pass
+        :param request: object describing the type and location of the value
+        :return: Future, giving async access to the returned value
+        """
diff --git a/sandbox/plc4py/pytest.ini b/sandbox/plc4py/pytest.ini
new file mode 100644
index 0000000000..039d0a2fbd
--- /dev/null
+++ b/sandbox/plc4py/pytest.ini
@@ -0,0 +1,2 @@
+[pytest]
+log_cli = true
\ No newline at end of file
diff --git a/sandbox/plc4py/tests/unit/plc4py/api/test_PlcRequest.py b/sandbox/plc4py/tests/unit/plc4py/api/test_PlcRequest.py
index 8a64dcf507..18e4c08ff4 100644
--- a/sandbox/plc4py/tests/unit/plc4py/api/test_PlcRequest.py
+++ b/sandbox/plc4py/tests/unit/plc4py/api/test_PlcRequest.py
@@ -84,7 +84,7 @@ async def test_read_request_builder_non_empty_request_not_connected(mocker) -> N
         response = await connection.execute(request)
 
     # verify that request has one field
-    assert response.code == PlcResponseCode.NOT_CONNECTED
+    assert response.response_code == PlcResponseCode.NOT_CONNECTED
 
 
 @pytest.mark.asyncio
@@ -107,9 +107,9 @@ async def test_read_request_builder_non_empty_request_connected_bool(mocker) ->
         )
 
     # verify that request has one field
-    assert response.code == PlcResponseCode.OK
+    assert response.response_code == PlcResponseCode.OK
 
-    value = response.values["Random Tag"][0].value
+    value = response.tags["Random Tag"].value
     assert not value.get_bool()
 
 
@@ -133,9 +133,9 @@ async def test_read_request_builder_non_empty_request_connected_int(mocker) -> N
         )
 
     # verify that request has one field
-    assert response.code == PlcResponseCode.OK
+    assert response.response_code == PlcResponseCode.OK
 
-    value = response.values["Random Tag"][0].value
+    value = response.tags["Random Tag"].value
     assert value.get_int() == 0
 
 
@@ -147,7 +147,7 @@ def test_read_response_boolean_response(mocker) -> None:
     """
     response = PlcReadResponse(
         PlcResponseCode.OK,
-        {"1:BOOL": [ResponseItem(PlcResponseCode.OK, PlcBOOL(True))]},
+        {"1:BOOL": ResponseItem(PlcResponseCode.OK, PlcBOOL(True))},
     )
     assert response.get_boolean("1:BOOL")
     assert isinstance(response.get_plc_value("1:BOOL"), PlcBOOL)
@@ -161,7 +161,7 @@ def test_read_response_int_response(mocker) -> None:
     """
     response = PlcReadResponse(
         PlcResponseCode.OK,
-        {"1:INT": [ResponseItem(PlcResponseCode.OK, PlcINT(10))]},
+        {"1:INT": ResponseItem(PlcResponseCode.OK, PlcINT(10))},
     )
     assert response.get_int("1:INT") == 10
     assert isinstance(response.get_plc_value("1:INT"), PlcINT)
diff --git a/sandbox/plc4py/tests/unit/plc4py/drivers/modbus/test_modbus_connection.py b/sandbox/plc4py/tests/unit/plc4py/drivers/modbus/test_modbus_connection.py
index ac42a830fb..04daefe7ea 100644
--- a/sandbox/plc4py/tests/unit/plc4py/drivers/modbus/test_modbus_connection.py
+++ b/sandbox/plc4py/tests/unit/plc4py/drivers/modbus/test_modbus_connection.py
@@ -19,6 +19,10 @@
 import time
 
 from plc4py.PlcDriverManager import PlcDriverManager
+from plc4py.api.value.PlcValue import PlcResponseCode
+import logging
+
+logger = logging.getLogger("testing")
 
 
 async def manual_test_plc_driver_modbus_connect():
@@ -28,9 +32,9 @@ async def manual_test_plc_driver_modbus_connect():
     assert not connection.is_connected()
 
 
-async def manual_test_plc_driver_modbus_read():
+async def test_plc_driver_modbus_read():
     driver_manager = PlcDriverManager()
-    async with driver_manager.connection("modbus://192.168.1.174:502") as connection:
+    async with driver_manager.connection("modbus://192.168.1.177:502") as connection:
         with connection.read_request_builder() as builder:
             builder.add_item("Random Tag", "4x00001[10]")
             request = builder.build()
@@ -38,4 +42,25 @@ async def manual_test_plc_driver_modbus_read():
         future = connection.execute(request)
         await future
         response = future.result()
+
+        for tag_name in response.tag_names:
+            if response.tags[tag_name].response_code == PlcResponseCode.OK:
+                num_values: int = len(response.tags[tag_name].value)
+                # If it's just one element, output just one single line.
+                if num_values == 1:
+                    logger.info(
+                        "Value[" + tag_name + "]: " + response.tags[tag_name].value
+                    )
+
+                # If it's more than one element, output each in a single row.
+                else:
+                    logger.info("Value[" + tag_name + "]:")
+                    for i in response.tags[tag_name].value.get_list():
+                        logger.info(" - " + str(i))
+
+            # Something went wrong, to output an error message instead.
+            else:
+                logger.error(
+                    "Error[" + tag_name + "]: " + response.tags[tag_name].name()
+                )
     pass
diff --git a/src/site/asciidoc/users/getting-started/plc4py.adoc b/src/site/asciidoc/users/getting-started/plc4py.adoc
index f8ca29295f..2a41ccd9bb 100644
--- a/src/site/asciidoc/users/getting-started/plc4py.adoc
+++ b/src/site/asciidoc/users/getting-started/plc4py.adoc
@@ -148,18 +148,10 @@ If this is `PlcResponseCode.OK`, everything is ok, however it could be one of th
 
 Assuming the return code was `OK`, we can continue accessing the data.
 
-As some tags support reading arrays, with the method `getNumberOfValues` the user can check how many items of a given type are returned.
-For convenience the response object has single-argument methods for accessing the data, which default to returning the first element.
+As all PlcValue items support the len property, the user can check how many items of a given type are returned by calling len(response.tags[tag_name].value)
 
-    response.getObject(fieldName)
+You can then treat the values in the PlcList as a list using response.tags[tag_name].value.get_list()
 
-If you want to access a given element number, please use the two-argument version instead:
-
-    response.getObject(fieldName, 42)
-
-PLC4X provides getters and setters for a wide variety of Java types and automatically handles the type conversion.
-However, when for example trying to get a long-value as a byte and the long-value exceeds the range supported by the smaller type, a `RuntimeException` of type `PlcIncompatibleDatatypeException`.
-In order to avoid causing this exception to be thrown, however there are `isValid{TypeName}` methods that you can use to check if the value is compatible.
 
 ==== Writing Data