Skip to content

Commit fbe1280

Browse files
authored
Add data types explanation to readme (#146)
* Add data types explanation to readme
1 parent dc10ec7 commit fbe1280

File tree

1 file changed

+83
-0
lines changed

1 file changed

+83
-0
lines changed

README.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,89 @@ For non-global cases see API methods argument list if method support using custo
6565

6666
See [Endian.php](src/Utils/Endian.php) for additional info and [Types.php](src/Utils/Types.php) for supported data types.
6767

68+
69+
## Data types
70+
71+
Modbus is binary protocol which revolves about addresses of Registers/Word (16bit, 2 byte of data) and Coils (1 bit of data).
72+
Coils are booleans but Register/Word or multiple Registers can hold different data types. Following is ways to access different
73+
data types from Registers:
74+
75+
Most of the for data types have optional arguments for providing Endian type. By default data is parsed as being Big Endian Low Word first endian.
76+
77+
Exaple: getting uint32 value as Little Endian Low Word First
78+
```php
79+
$dword->getUInt32(Endian::LITTLE_ENDIAN | Endian::LOW_WORD_FIRST);
80+
```
81+
82+
### 1bit - 16bit data types
83+
84+
1-16bit data types are hold by `Word` class which hold 2 bytes of data.
85+
```php
86+
$address = 100;
87+
$word = $response->getWordAt($address);
88+
```
89+
90+
Following methods exists to get different types out of single `Word` instance:
91+
* `boolean` - 1bit, true/false, `$word->isBitSet(11)`
92+
* `byte` - 8bit, 1 byte, range 0 to 255
93+
* first byte of Word (0) `$word->getHighByteAsInt()`
94+
* last byte of Word (1) `$word->getLowByteAsInt()`
95+
* `uint16` - 16bit, 2 byte, range 0 to 65535 `$word->getUInt16()`
96+
* `int16` - 16bit, 2 byte, range -32768 to 32767 `$word->getInt16()`
97+
98+
and following additional methods:
99+
* `$word->getBytes()` return Words as array of 2 integers (0-255)
100+
101+
102+
### 32bit data types
103+
104+
17-32bit data types are hold by `DoubleWord` class which hold 4 bytes of data.
105+
```php
106+
$address = 100;
107+
$dword = $response->getDoubleWordAt($address);
108+
```
109+
110+
Following methods exists to get different types out of single `DoubleWord` instance:
111+
* `uint32` - 32bit, 4 bytes, range 0 to 4294967295, `$dword->getUInt32()`
112+
* `int32` - 64bit, 8 bytes, range -2147483648 to 2147483647, `$dword->getInt32()`
113+
* `float` - 64bit, 8 bytes, range -3.4e+38 to 3.4e+38, `$dword->getFloat()`
114+
115+
and following additional methods:
116+
* `$dword->getBytes()` return DoubleWord as array of 4 integers (0-255)
117+
* `$dword->getHighBytesAsWord()` returns first 2 bytes as `Word`
118+
* `$dword->getLowBytesAsWord()` returns last 2 bytes as `Word`
119+
120+
121+
### 64bit data types
122+
123+
64bit data types are hold by `QuadWord` class which hold 8 bytes of data.
124+
NB: 64-bit PHP supports only up to 63-bit (signed) integers.
125+
```php
126+
$address = 100;
127+
$qword = $response->getQuadWordAt($address);
128+
```
129+
130+
Following methods exists to get different types out of single `QuadWord` instance:
131+
* `uint32` - 64bit, 8 bytes, range 0 to 9223372036854775807, `$dword->getUInt64()`
132+
* `int32` - 64bit, 8 bytes, range -9223372036854775808 to 9223372036854775807, `$dword->getInt64()`
133+
* `double` - 64bit, 8 bytes, range 2.2250738585072e-308 to 1.7976931348623e+308, `$dword->getDouble()`
134+
135+
and following additional methods:
136+
* `$qword->getBytes()` return `QuadWord` as array of 8 integers (0-255)
137+
* `$qword->getHighBytesAsDoubleWord()` returns first 4 bytes as `DoubleWord`
138+
* `$qword->getLowBytesAsDoubleWord()` returns last 4 bytes as `DoubleWord`
139+
140+
141+
### Strings
142+
143+
ASCII (8bit character) string can be extracted from response as utf-8 string
144+
```php
145+
$address = 20;
146+
$length = 10;
147+
$string = $response->getAsciiStringAt($address, $length);
148+
```
149+
150+
68151
## Example of Modbus TCP (fc3 - read holding registers)
69152

70153
Some of the Modbus function examples are in [examples/](examples) folder

0 commit comments

Comments
 (0)