Added Packet::isCompleteLengthRTU() to help checking if packet is complete RTU packet

Author: aldas

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+# [3.1.0] - 2022-10-16
+
+* Added `Packet::isCompleteLengthRTU()` to help checking if packet is complete RTU packet. Helps when receiving fragmented packets.
+* Example for RTU over TCP with higher level API [examples/rtu_over_tcp_with_higherlevel_api.php](examples/rtu_over_tcp_with_higherlevel_api.php)
+
 ## [3.0.1] - 2022-09-29
 
 * `ResultContainer.offsetGet` was missing return type

examples/rtu.php

@@ -3,6 +3,7 @@
 use ModbusTcpClient\Network\BinaryStreamConnection;
 use ModbusTcpClient\Packet\ModbusFunction\ReadHoldingRegistersRequest;
 use ModbusTcpClient\Packet\RtuConverter;
+use ModbusTcpClient\Utils\Packet;
 
 require __DIR__ . '/../vendor/autoload.php';
 require __DIR__ . '/logger.php';
@@ -12,11 +13,7 @@
     ->setHost('127.0.0.1')
     ->setReadTimeoutSec(3) // increase read timeout to 3 seconds
     ->setIsCompleteCallback(function ($binaryData, $streamIndex) {
-        // Do not check for complete TCP packet structure. Default implementation works only for Modbus TCP.
-        // Modbus TCP has 7 byte header and this function checks for it and whole packet to be complete. RTU does
-        // not have that.
-        // Read about differences here: https://www.simplymodbus.ca/TCP.htm
-        return true;
+        return Packet::isCompleteLengthRTU($binaryData);
     })
     ->setLogger(new EchoLogger())
     ->build();

examples/rtu_over_tcp_with_higherlevel_api.php

@@ -0,0 +1,53 @@
+<?php
+
+use ModbusTcpClient\Composer\Read\ReadRegistersBuilder;
+use ModbusTcpClient\Composer\Read\Register\ReadRegisterRequest;
+use ModbusTcpClient\Network\BinaryStreamConnection;
+use ModbusTcpClient\Packet\RtuConverter;
+use ModbusTcpClient\Utils\Packet;
+
+require __DIR__ . '/../vendor/autoload.php';
+require __DIR__ . '/logger.php';
+
+// Modbus server simulator https://www.modbusdriver.com/diagslave.html
+// Start simulator with `./diagslave -m enc -a 1 -p 5020`
+
+$connection = BinaryStreamConnection::getBuilder()
+    ->setPort(5020)
+    ->setHost('127.0.0.1')
+    ->setReadTimeoutSec(0.5)
+    ->setIsCompleteCallback(function ($binaryData, $streamIndex) {
+        return Packet::isCompleteLengthRTU($binaryData);
+    })
+    ->setLogger(new EchoLogger())
+    ->build();
+
+$unitID = 1; // RTU packet slave id equivalent is Modbus TCP unitId
+$fc3requests = ReadRegistersBuilder::newReadHoldingRegisters('no_address', $unitID) // uri/address does not matter because we use $connection
+    ->int16(1, 'address1_value') // or whatever data type that value is in that register
+    ->uint16(2, 'address2_value')
+    // See `ReadRegistersBuilder.php` for available data type methods
+    ->build(); // returns array of ReadHoldingRegistersRequest requests
+
+try {
+    /** @var $request ReadRegisterRequest */
+    foreach ($fc3requests as $request) {
+        echo 'Packet to be sent (in hex): ' . $request->getRequest()->toHex() . PHP_EOL;
+        $rtuPacket = RtuConverter::toRtu($request->getRequest());
+
+        $binaryData = $connection->connect()->sendAndReceive($rtuPacket);
+        echo 'RTU Binary received (in hex):   ' . unpack('H*', $binaryData)[1] . PHP_EOL;
+
+        $tcpResponsePacket = RtuConverter::fromRtu($binaryData);
+
+        echo 'Data parsed from packet (bytes):' . PHP_EOL;
+        $result = $request->parse($tcpResponsePacket);
+        print_r($result);
+    }
+} catch (Exception $exception) {
+    echo 'An exception occurred' . PHP_EOL;
+    echo $exception->getMessage() . PHP_EOL;
+    echo $exception->getTraceAsString() . PHP_EOL;
+} finally {
+    $connection->close();
+}

examples/rtu_usb_to_serial_stream.php

@@ -4,6 +4,7 @@
 use ModbusTcpClient\Packet\ModbusFunction\ReadInputRegistersRequest;
 use ModbusTcpClient\Packet\ModbusFunction\ReadInputRegistersResponse;
 use ModbusTcpClient\Packet\RtuConverter;
+use ModbusTcpClient\Utils\Packet;
 
 require __DIR__ . '/../vendor/autoload.php';
 require __DIR__ . '/logger.php';
@@ -12,11 +13,7 @@
     ->setUri('/dev/ttyUSB0')
     ->setProtocol('serial')
     ->setIsCompleteCallback(static function ($binaryData, $streamIndex): bool {
-        // NB: returning always true could lead to problems with reading fragmented packets (so we returning too early)
-        // safest way would be to calculate bytes length that we expect and error response length.
-        // Example for error: 5 bytes = 1 unit id + 1 byte for function code + 1 byte for error code + 2 bytes for CRC
-        // Example for FC4 with quantity 2: 8 bytes = 1 unit id + 1 byte for function code + 2 bytes start address + 2 * quantity
-        return true;
+        return Packet::isCompleteLengthRTU($binaryData);
     })
     ->setLogger(new EchoLogger())
     ->build();

src/Utils/Packet.php

@@ -5,6 +5,7 @@
 
 
 use ModbusTcpClient\Network\IOException;
+use ModbusTcpClient\Packet\ErrorResponse;
 
 final class Packet
 {
@@ -14,11 +15,11 @@ private function __construct()
     }
 
     /**
-     * isCompleteLength checks if binary string is complete modbus packet
+     * isCompleteLength checks if binary string is complete modbus TCP packet
      * NB: this function works only for MODBUS TCP packets
      *
      * @param string|null $binaryData binary string to be checked
-     * @return bool true if data is actual error packet
+     * @return bool true if data is actual modbus TCP packet
      */
     public static function isCompleteLength(string|null $binaryData): bool
     {
@@ -37,4 +38,35 @@ public static function isCompleteLength(string|null $binaryData): bool
         return $length === $expectedLength;
     }
 
+    /**
+     * isCompleteLengthRTU checks if binary string is complete modbus RTU packet
+     * NB: this function works only for MODBUS RTU packets
+     *
+     * @param string|null $binaryData binary string to be checked
+     * @return bool true if data is actual error packet
+     */
+    public static function isCompleteLengthRTU(string|null $binaryData): bool
+    {
+        // minimal RTU packet length is 5 bytes (1 byte unit id + 1 byte function code + 1 byte of error code or byte length + 2 bytes for CRC)
+        $length = strlen($binaryData);
+        if ($length < 5) {
+            return false;
+        }
+        if ((ord($binaryData[1]) & ErrorResponse::EXCEPTION_BITMASK) > 0) { // seems to be error response
+            return true;
+        }
+        // if it is not error response then 3rd byte contains data length in bytes
+
+        // trailing 3 bytes are = unit id + function code + data length in bytes
+        // next is N bytes of data that should match 3rd byte value
+        // and 2 bytes for CRC
+        // so adding these number is what complete packet would be
+        $expectedLength = 3 + ord($binaryData[2]) + 2;
+
+        if ($length > $expectedLength) {
+            throw new IOException('packet length more bytes than expected');
+        }
+        return $length === $expectedLength;
+    }
+
 }

tests/unit/Utils/PacketTest.php

@@ -37,4 +37,31 @@ public function testIsCompleteLengthTooLong()
         Packet::isCompleteLength("\x81\x80\x00\x00\x00\x05\x03\x03\x02\xCD\x6B\xFF");
     }
 
+    public function isCompleteLengthRTUProvider(): array
+    {
+        return [
+            'complete error packet is complete' => ["\x00\x81\x03\x51\x91", true],
+            'short incomplete error packet is not complete' => ["\x00\x81\x03\x51", false],
+            'read holding registers (f3) response packet is complete' => ["\x01\x03\x04\x00\x00\x00\x00\xfa\x33", true],
+            'incomplete read holding registers (f3) response packet is not complete' => ["\x01\x03\x04\x00\x00\x00\x00", false],
+        ];
+    }
+
+    /**
+     * @dataProvider isCompleteLengthRTUProvider
+     */
+    public function testIsCompleteLengthRTUh($binaryData, $expect)
+    {
+        $is = Packet::isCompleteLengthRTU($binaryData);
+        $this->assertEquals($expect, $is);
+    }
+
+    public function testIsCompleteLengthRTUTooLong()
+    {
+        $this->expectExceptionMessage("packet length more bytes than expected");
+        $this->expectException(IOException::class);
+
+        Packet::isCompleteLengthRTU("\x01\x03\x04\x00\x00\x00\x00\xfa\x33\xFF");
+    }
+
 }