Allow high level api to specify custom endian for each address

aldas · aldas · commit 4d7b65985a18 · 2021-05-04T22:32:21.000+03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,12 @@ 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).
 
+## [2.2.0] - 2021-05-04
+
+### Added
+
+* Allow high level API setting custom endian for each address with `ReadRegistersBuilder` and `ReadRegisterAddress` classes.
+
 ## [2.1.1] - 2021-01-26
 
 ### Fixed
diff --git a/README.md b/README.md
@@ -53,6 +53,13 @@ Library supports following byte and word orders:
 * Little endian (DCBA - word1 = 0x3412, word2 = 0x7856)
 * Little endian low word first (BADC - word1 = 0x7856, word2 = 0x3412)
 
+Default (global) endianess used for parsing can be changed with:
+```php
+Endian::$defaultEndian = Endian::BIG_ENDIAN_LOW_WORD_FIRST;
+```
+
+For non-global cases see API methods argument list if method support using custom endianess.
+
 See [Endian.php](src/Utils/Endian.php) for additional info and [Types.php](src/Utils/Types.php) for supported data types.
 
 ## Example of Modbus TCP (fc3 - read holding registers)
@@ -90,8 +97,9 @@ $fc3 = ReadRegistersBuilder::newReadHoldingRegisters($address, $unitID)
     ->build(); // returns array of 3 ReadHoldingRegistersRequest requests
 
 // this will use PHP non-blocking stream io to recieve responses
-$responses = (new NonBlockingClient(['readTimeoutSec' => 0.2]))->sendRequests($fc3);
-print_r($responses);
+$responseContainer = (new NonBlockingClient(['readTimeoutSec' => 0.2]))->sendRequests($fc3);
+print_r($responseContainer->getData()); // array of assoc. arrays (keyed by address name)
+print_r($responseContainer->getErrors());
 ```
 Response structure
 ```php
diff --git a/examples/example_parallel_requests.php b/examples/example_parallel_requests.php
@@ -5,6 +5,9 @@
 use ModbusTcpClient\Composer\Address;
 use ModbusTcpClient\Composer\Read\ReadRegistersBuilder;
 use ModbusTcpClient\Network\NonBlockingClient;
+use ModbusTcpClient\Utils\Endian;
+
+Endian::$defaultEndian = Endian::BIG_ENDIAN_LOW_WORD_FIRST; // set default (global) endian used for parsing data
 
 $fc3 = ReadRegistersBuilder::newReadHoldingRegisters('tcp://127.0.0.1:5022')
     ->bit(256, 15, 'pump2_feedbackalarm_do')
@@ -14,7 +17,7 @@
     ->int16(657, 'battery3_voltage_wo')
     ->uint16(658, 'wind_angle_wo')
     ->int32(659, 'gps_speed')
-    ->uint32(661, 'distance_total_wo')
+    ->uint32(661, 'distance_total_wo', null, null, Endian::BIG_ENDIAN) // use custom endianess
     ->uint64(663, 'gen2_energyw0_wo')
     ->float(667, 'longitude')
     ->string(669, 10, 'username')
@@ -35,4 +38,5 @@ function (\Exception $exception, Address $address, $response) {
     ->build(); // returns array of 3 requests
 
 $responseContainer = (new NonBlockingClient(['readTimeoutSec' => 0.2]))->sendRequests($fc3);
-print_r($responseContainer);
+print_r($responseContainer->getData()); // array of assoc. arrays (keyed by address name)
+print_r($responseContainer->getErrors());
diff --git a/examples/fc3.php b/examples/fc3.php
@@ -4,10 +4,13 @@
 use ModbusTcpClient\Packet\ModbusFunction\ReadHoldingRegistersRequest;
 use ModbusTcpClient\Packet\ModbusFunction\ReadHoldingRegistersResponse;
 use ModbusTcpClient\Packet\ResponseFactory;
+use ModbusTcpClient\Utils\Endian;
 
 require __DIR__ . '/../vendor/autoload.php';
 require __DIR__ . '/logger.php';
 
+Endian::$defaultEndian = Endian::BIG_ENDIAN_LOW_WORD_FIRST; // set default (global) endian used for parsing data
+
 $connection = BinaryStreamConnection::getBuilder()
     ->setPort(5020)
     ->setHost('127.0.0.1')
diff --git a/src/Composer/Read/ReadRegistersBuilder.php b/src/Composer/Read/ReadRegistersBuilder.php
@@ -14,6 +14,7 @@
 use ModbusTcpClient\Exception\InvalidArgumentException;
 use ModbusTcpClient\Packet\ModbusFunction\ReadHoldingRegistersRequest;
 use ModbusTcpClient\Packet\ModbusFunction\ReadInputRegistersRequest;
+use ModbusTcpClient\Utils\Endian;
 
 class ReadRegistersBuilder
 {
@@ -109,6 +110,11 @@ public function fromArray(array $register): ReadRegistersBuilder
             throw new InvalidArgumentException('empty or unknown type for address given');
         }
 
+        $endian = $register['endian'] ?? null;
+        if ($endian === null) {
+            $endian = Endian::$defaultEndian;
+        }
+
         switch ($addressType) {
             case Address::TYPE_BIT:
                 $this->bit($address, $register['bit'] ?? 0, $register['name'] ?? null, $callback, $errorCallback);
@@ -117,25 +123,25 @@ public function fromArray(array $register): ReadRegistersBuilder
                 $this->byte($address, (bool)($register['firstByte'] ?? true), $register['name'] ?? null, $callback, $errorCallback);
                 break;
             case Address::TYPE_INT16:
-                $this->int16($address, $register['name'] ?? null, $callback, $errorCallback);
+                $this->int16($address, $register['name'] ?? null, $callback, $errorCallback, $endian);
                 break;
             case Address::TYPE_UINT16:
-                $this->uint16($address, $register['name'] ?? null, $callback, $errorCallback);
+                $this->uint16($address, $register['name'] ?? null, $callback, $errorCallback, $endian);
                 break;
             case Address::TYPE_INT32:
-                $this->int32($address, $register['name'] ?? null, $callback, $errorCallback);
+                $this->int32($address, $register['name'] ?? null, $callback, $errorCallback, $endian);
                 break;
             case Address::TYPE_UINT32:
-                $this->uint32($address, $register['name'] ?? null, $callback, $errorCallback);
+                $this->uint32($address, $register['name'] ?? null, $callback, $errorCallback, $endian);
                 break;
             case Address::TYPE_INT64:
-                $this->int64($address, $register['name'] ?? null, $callback, $errorCallback);
+                $this->int64($address, $register['name'] ?? null, $callback, $errorCallback, $endian);
                 break;
             case Address::TYPE_UINT64:
-                $this->uint64($address, $register['name'] ?? null, $callback, $errorCallback);
+                $this->uint64($address, $register['name'] ?? null, $callback, $errorCallback, $endian);
                 break;
             case Address::TYPE_FLOAT:
-                $this->float($address, $register['name'] ?? null, $callback, $errorCallback);
+                $this->float($address, $register['name'] ?? null, $callback, $errorCallback, $endian);
                 break;
             case Address::TYPE_STRING:
                 $byteLength = $register['length'] ?? null;
@@ -161,39 +167,137 @@ public function byte(int $address, bool $firstByte = true, string $name = null,
         return $this->addAddress(new ByteReadRegisterAddress($address, $firstByte, $name, $callback, $errorCallback));
     }
 
-    public function int16(int $address, string $name = null, callable $callback = null, callable $errorCallback = null): ReadRegistersBuilder
+    public function int16(
+        int $address,
+        string $name = null,
+        callable $callback = null,
+        callable $errorCallback = null,
+        int $endian = null
+    ): ReadRegistersBuilder
     {
-        return $this->addAddress(new ReadRegisterAddress($address, ReadRegisterAddress::TYPE_INT16, $name, $callback, $errorCallback));
+        $r = new ReadRegisterAddress(
+            $address,
+            ReadRegisterAddress::TYPE_INT16,
+            $name,
+            $callback,
+            $errorCallback,
+            $endian
+        );
+        return $this->addAddress($r);
     }
 
-    public function uint16(int $address, string $name = null, callable $callback = null, callable $errorCallback = null): ReadRegistersBuilder
+    public function uint16(
+        int $address,
+        string $name = null,
+        callable $callback = null,
+        callable $errorCallback = null,
+        int $endian = null
+    ): ReadRegistersBuilder
     {
-        return $this->addAddress(new ReadRegisterAddress($address, ReadRegisterAddress::TYPE_UINT16, $name, $callback, $errorCallback));
+        $r = new ReadRegisterAddress(
+            $address,
+            ReadRegisterAddress::TYPE_UINT16,
+            $name,
+            $callback,
+            $errorCallback,
+            $endian
+        );
+        return $this->addAddress($r);
     }
 
-    public function int32(int $address, string $name = null, callable $callback = null, callable $errorCallback = null): ReadRegistersBuilder
+    public function int32(
+        int $address,
+        string $name = null,
+        callable $callback = null,
+        callable $errorCallback = null,
+        int $endian = null
+    ): ReadRegistersBuilder
     {
-        return $this->addAddress(new ReadRegisterAddress($address, ReadRegisterAddress::TYPE_INT32, $name, $callback, $errorCallback));
+        $r = new ReadRegisterAddress(
+            $address,
+            ReadRegisterAddress::TYPE_INT32,
+            $name,
+            $callback,
+            $errorCallback,
+            $endian
+        );
+        return $this->addAddress($r);
     }
 
-    public function uint32(int $address, string $name = null, callable $callback = null, callable $errorCallback = null): ReadRegistersBuilder
+    public function uint32(
+        int $address,
+        string $name = null,
+        callable $callback = null,
+        callable $errorCallback = null,
+        int $endian = null
+    ): ReadRegistersBuilder
     {
-        return $this->addAddress(new ReadRegisterAddress($address, ReadRegisterAddress::TYPE_UINT32, $name, $callback, $errorCallback));
+        $r = new ReadRegisterAddress(
+            $address,
+            ReadRegisterAddress::TYPE_UINT32,
+            $name,
+            $callback,
+            $errorCallback,
+            $endian
+        );
+        return $this->addAddress($r);
     }
 
-    public function uint64(int $address, string $name = null, callable $callback = null, callable $errorCallback = null): ReadRegistersBuilder
+    public function uint64(
+        int $address,
+        string $name = null,
+        callable $callback = null,
+        callable $errorCallback = null,
+        int $endian = null
+    ): ReadRegistersBuilder
     {
-        return $this->addAddress(new ReadRegisterAddress($address, ReadRegisterAddress::TYPE_UINT64, $name, $callback, $errorCallback));
+        $r = new ReadRegisterAddress(
+            $address,
+            ReadRegisterAddress::TYPE_UINT64,
+            $name,
+            $callback,
+            $errorCallback,
+            $endian
+        );
+        return $this->addAddress($r);
     }
 
-    public function int64(int $address, string $name = null, callable $callback = null, callable $errorCallback = null): ReadRegistersBuilder
+    public function int64(
+        int $address,
+        string $name = null,
+        callable $callback = null,
+        callable $errorCallback = null,
+        int $endian = null
+    ): ReadRegistersBuilder
     {
-        return $this->addAddress(new ReadRegisterAddress($address, ReadRegisterAddress::TYPE_INT64, $name, $callback, $errorCallback));
+        $r = new ReadRegisterAddress(
+            $address,
+            ReadRegisterAddress::TYPE_INT64,
+            $name,
+            $callback,
+            $errorCallback,
+            $endian
+        );
+        return $this->addAddress($r);
     }
 
-    public function float(int $address, string $name = null, callable $callback = null, callable $errorCallback = null): ReadRegistersBuilder
+    public function float(
+        int $address,
+        string $name = null,
+        callable $callback = null,
+        callable $errorCallback = null,
+        int $endian = null
+    ): ReadRegistersBuilder
     {
-        return $this->addAddress(new ReadRegisterAddress($address, ReadRegisterAddress::TYPE_FLOAT, $name, $callback, $errorCallback));
+        $r = new ReadRegisterAddress(
+            $address,
+            ReadRegisterAddress::TYPE_FLOAT,
+            $name,
+            $callback,
+            $errorCallback,
+            $endian
+        );
+        return $this->addAddress($r);
     }
 
     public function string(int $address, int $byteLength, string $name = null, callable $callback = null, callable $errorCallback = null): ReadRegistersBuilder
diff --git a/src/Composer/Read/Register/ReadRegisterAddress.php b/src/Composer/Read/Register/ReadRegisterAddress.php
@@ -6,6 +6,7 @@
 use ModbusTcpClient\Composer\Address;
 use ModbusTcpClient\Composer\RegisterAddress;
 use ModbusTcpClient\Packet\ModbusResponse;
+use ModbusTcpClient\Utils\Endian;
 
 class ReadRegisterAddress extends RegisterAddress
 {
@@ -18,10 +19,21 @@ class ReadRegisterAddress extends RegisterAddress
     /** @var callable */
     private $errorCallback;
 
-    public function __construct(int $address, string $type, string $name = null, callable $callback = null, callable $errorCallback = null)
+    /** @var int */
+    private $endian;
+
+    public function __construct(
+        int $address,
+        string $type,
+        string $name = null,
+        callable $callback = null,
+        callable $errorCallback = null,
+        int $endian = null
+    )
     {
         parent::__construct($address, $type);
 
+        $this->endian = $endian === null ? Endian::$defaultEndian : $endian;
         $this->name = $name ?: "{$type}_{$address}";
         $this->callback = $callback;
         $this->errorCallback = $errorCallback;
@@ -45,25 +57,25 @@ protected function extractInternal(ModbusResponse $response)
         $result = null;
         switch ($this->type) {
             case Address::TYPE_INT16:
-                $result = $response->getWordAt($this->address)->getInt16();
+                $result = $response->getWordAt($this->address)->getInt16($this->endian);
                 break;
             case Address::TYPE_UINT16:
-                $result = $response->getWordAt($this->address)->getUInt16();
+                $result = $response->getWordAt($this->address)->getUInt16($this->endian);
                 break;
             case Address::TYPE_INT32:
-                $result = $response->getDoubleWordAt($this->address)->getInt32();
+                $result = $response->getDoubleWordAt($this->address)->getInt32($this->endian);
                 break;
             case Address::TYPE_UINT32:
-                $result = $response->getDoubleWordAt($this->address)->getUInt32();
+                $result = $response->getDoubleWordAt($this->address)->getUInt32($this->endian);
                 break;
             case Address::TYPE_FLOAT:
-                $result = $response->getDoubleWordAt($this->address)->getFloat();
+                $result = $response->getDoubleWordAt($this->address)->getFloat($this->endian);
                 break;
             case Address::TYPE_INT64:
-                $result = $response->getQuadWordAt($this->address)->getInt64();
+                $result = $response->getQuadWordAt($this->address)->getInt64($this->endian);
                 break;
             case Address::TYPE_UINT64:
-                $result = $response->getQuadWordAt($this->address)->getUInt64();
+                $result = $response->getQuadWordAt($this->address)->getUInt64($this->endian);
                 break;
         }
         return $result;
@@ -96,4 +108,9 @@ public function getName(): string
     {
         return $this->name;
     }
+
+    public function getEndian(): int
+    {
+        return $this->endian;
+    }
 }
diff --git a/tests/unit/Composer/Read/ReadRegistersBuilderTest.php b/tests/unit/Composer/Read/ReadRegistersBuilderTest.php
diff --git a/tests/unit/Composer/Read/Register/ReadRegisterAddressTest.php b/tests/unit/Composer/Read/Register/ReadRegisterAddressTest.php
