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
commit 1c0eadd896666289d2eb98ac28eea2fb8ad5b253
Author: Ben Hutcheson <ben.hut...@gmail.com>
AuthorDate: Mon Feb 19 05:12:10 2024 +0100
fix(plc4py): Continue working through help docs. Cleaned up the response
---
sandbox/plc4py/plc4py/api/messages/PlcResponse.py | 35 +++++-------
sandbox/plc4py/plc4py/api/value/PlcValue.py | 5 ++
.../plc4py/plc4py/drivers/modbus/ModbusDevice.py | 12 ++--
sandbox/plc4py/plc4py/drivers/umas/UmasDevice.py | 9 ++-
.../plc4py/spi/messages/utils/ResponseItem.py | 2 +-
.../asciidoc/users/getting-started/plc4py.adoc | 64 +++++++++-------------
6 files changed, 54 insertions(+), 73 deletions(-)
diff --git a/sandbox/plc4py/plc4py/api/messages/PlcResponse.py
b/sandbox/plc4py/plc4py/api/messages/PlcResponse.py
index cc546d730d..115b8573a0 100644
--- a/sandbox/plc4py/plc4py/api/messages/PlcResponse.py
+++ b/sandbox/plc4py/plc4py/api/messages/PlcResponse.py
@@ -32,19 +32,16 @@ class PlcResponse(PlcMessage):
from a plc to the plc4x system.
"""
- code: PlcResponseCode
+ response_code: PlcResponseCode
@dataclass
class PlcTagResponse(PlcResponse):
- values: Dict[str, List[ResponseItem[PlcValue]]]
+ tags: Dict[str, ResponseItem[PlcValue]]
@property
def tag_names(self):
- return [tag_name for tag_name in self.values.keys()]
-
- def response_code(self, name: str) -> PlcResponseCode:
- pass
+ return [tag_name for tag_name in self.tags.keys()]
@dataclass
@@ -53,23 +50,20 @@ class PlcReadResponse(PlcTagResponse):
Response to a {@link PlcReadRequest}.
"""
- def get_plc_value(self, name: str, index: int = 0) -> PlcValue:
- return self.values[name][index].value
+ def get_plc_value(self, name: str) -> PlcValue:
+ return self.tags[name].value
- def number_of_values(self, name: str) -> int:
- return len(self.values[name])
+ def is_boolean(self, name: str):
+ return isinstance(self.tags[name].value.value, bool)
- def is_boolean(self, name: str, index: int = 0):
- return isinstance(self.values[name][index].value.value, bool)
+ def get_boolean(self, name: str) -> bool:
+ return cast(bool, self.tags[name].value.value)
- def get_boolean(self, name: str, index: int = 0) -> bool:
- return cast(bool, self.values[name][index].value.value)
+ def is_int(self, name: str):
+ return isinstance(self.tags[name].value.value, int)
- def is_int(self, name: str, index: int = 0):
- return isinstance(self.values[name][index].value.value, int)
-
- def get_int(self, name: str, index: int = 0) -> int:
- return cast(int, self.values[name][index].value.value)
+ def get_int(self, name: str) -> int:
+ return cast(int, self.tags[name].value.value)
@dataclass
@@ -80,9 +74,6 @@ class PlcQueryResponse(PlcResponse):
def tag_names(self):
return [tag_name for tag_name in self.tags.keys()]
- def response_code(self, name: str) -> PlcResponseCode:
- pass
-
@dataclass
class PlcBrowseResponse(PlcQueryResponse):
diff --git a/sandbox/plc4py/plc4py/api/value/PlcValue.py
b/sandbox/plc4py/plc4py/api/value/PlcValue.py
index b154a48ffd..6df4486dc0 100644
--- a/sandbox/plc4py/plc4py/api/value/PlcValue.py
+++ b/sandbox/plc4py/plc4py/api/value/PlcValue.py
@@ -46,6 +46,11 @@ class PlcValue(Generic[T], ABC):
def get_raw(self):
return self.value
+ def __len__(self):
+ if isinstance(self.value, list):
+ return len(self.value)
+ return 1
+
class PlcResponseCode(Enum):
OK = auto()
diff --git a/sandbox/plc4py/plc4py/drivers/modbus/ModbusDevice.py
b/sandbox/plc4py/plc4py/drivers/modbus/ModbusDevice.py
index 9a0157d2c1..5b06e6e717 100644
--- a/sandbox/plc4py/plc4py/drivers/modbus/ModbusDevice.py
+++ b/sandbox/plc4py/plc4py/drivers/modbus/ModbusDevice.py
@@ -121,14 +121,10 @@ class ModbusDevice:
result = message_future.result()
if isinstance(result, ModbusPDUError):
- response_items = [
- 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_items}
+ PlcResponseCode.OK, {request.tag_names[0]: response_item}
)
return response
@@ -147,9 +143,9 @@ class ModbusDevice:
request.tags[request.tag_names[0]].quantity,
)
- response_items = [ResponseItem(PlcResponseCode.OK, returned_value)]
+ response_item = ResponseItem(PlcResponseCode.OK, returned_value)
response = PlcReadResponse(
- PlcResponseCode.OK, {request.tag_names[0]: response_items}
+ PlcResponseCode.OK, {request.tag_names[0]: response_item}
)
return response
diff --git a/sandbox/plc4py/plc4py/drivers/umas/UmasDevice.py
b/sandbox/plc4py/plc4py/drivers/umas/UmasDevice.py
index a9253428cc..b0e80efb2d 100644
--- a/sandbox/plc4py/plc4py/drivers/umas/UmasDevice.py
+++ b/sandbox/plc4py/plc4py/drivers/umas/UmasDevice.py
@@ -364,7 +364,7 @@ class UmasDevice:
read_buffer = ReadBufferByteBased(
bytearray(variable_name_response.block), ByteOrder.LITTLE_ENDIAN
)
- values: Dict[str, List[ResponseItem[PlcValue]]] = {}
+ values: Dict[str, ResponseItem[PlcValue]] = {}
for key, tag in sorted_tags:
request_tag = request.tags[key]
if tag.is_array:
@@ -372,13 +372,12 @@ class UmasDevice:
else:
quantity = 1
- response_items = [
- ResponseItem(
+ response_item = ResponseItem(
PlcResponseCode.OK,
DataItem.static_parse(read_buffer, request_tag.data_type,
quantity),
)
- ]
- values[key] = response_items
+
+ values[key] = response_item
response = PlcReadResponse(PlcResponseCode.OK, values)
return response
diff --git a/sandbox/plc4py/plc4py/spi/messages/utils/ResponseItem.py
b/sandbox/plc4py/plc4py/spi/messages/utils/ResponseItem.py
index 4ded5f97bb..a26cfdb209 100644
--- a/sandbox/plc4py/plc4py/spi/messages/utils/ResponseItem.py
+++ b/sandbox/plc4py/plc4py/spi/messages/utils/ResponseItem.py
@@ -28,5 +28,5 @@ T = TypeVar("T", bound=PlcValue)
@dataclass
class ResponseItem(Generic[T], ABC):
- code: PlcResponseCode
+ response_code: PlcResponseCode
value: T
diff --git a/src/site/asciidoc/users/getting-started/plc4py.adoc
b/src/site/asciidoc/users/getting-started/plc4py.adoc
index c10936eb59..f8ca29295f 100644
--- a/src/site/asciidoc/users/getting-started/plc4py.adoc
+++ b/src/site/asciidoc/users/getting-started/plc4py.adoc
@@ -96,57 +96,47 @@ If you are using the `BrowseApi` you might also have been
provided with `Tag` ob
The request is sent to the PLC by issuing the `execute` method on the request
object:
----
-CompletableFuture<? extends PlcReadResponse> asyncResponse =
readRequest.execute();
-asyncResponse.whenComplete((response, throwable) -> {
- try {
- ... process the response ...
- } catch (Exception e) {
- ... Handle any errors ...
- }
-});
+try:
+ future = connection.execute(request)
+ await future
+ response = future.result()
+except TimeOutException:
+ # Handle timeout error
+except ...
+ # Handle all your other errors
+
----
In general, all requests are executed asynchronously.
-As soon as the request is fully processed, the callback gets called and will
contain a `readResponse`, if everything went right or a `throwable` if there
were problems.
+As soon as the request is fully processed, the callback gets called and will
contain a `readResponse`, if everything went right or an excception if there
were problems.
-However, if you want to write your code in a more synchronous fashion, the
following alternative will provide this:
-
-----
-PlcReadResponse response = readRequest.execute().get(5000,
TimeUnit.MILLISECONDS);
-----
-
-Processing of the responses is identical in both cases in the synchronous
approach you however need to catch any exceptions.
The following example will demonstrate some of the options you have:
----
-for (String tagName : response.getTagNames()) {
- if(response.getResponseCode(tagName) == PlcResponseCode.OK) {
- int numValues = response.getNumberOfValues(tagName);
- // If it's just one element, output just one single line.
- if(numValues == 1) {
- logger.info("Value[" + tagName + "]: " +
response.getObject(tagName));
- }
- // If it's more than one element, output each in a single row.
- else {
- logger.info("Value[" + tagName + "]:");
- for(int i = 0; i < numValues; i++) {
- logger.info(" - " + response.getObject(tagName, i));
- }
- }
- }
- // Something went wrong, to output an error message instead.
- else {
- logger.error("Error[" + tagName + "]: " +
response.getResponseCode(tagName).name());
- }
-}
+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())
----
In the for-loop, we are demonstrating how the user can iterate over the tag
aliases in the response.
In case of an ordinary read request, this will be predefined by the items in
the request, however in case of a subscription response, the response might
only contain some of the items that were subscribed.
Before accessing the data, it is advisable to check if an item was correctly
returned.
-This is done by the `getResponseCode` method for a given alias.
+This is done by the `response_code` property for a given alias.
If this is `PlcResponseCode.OK`, everything is ok, however it could be one of
the following:
- NOT_FOUND
