==== MBTCP_Read ====

Read a single register from a Modbus/TCP server

=== Description ===

<code>MBTCP_Read(ip, unitid, cmd, reg, format=BT_UINT16, &error)</code>

This command issues a Modbus/TCP read command and waits for a valid reply.
If an error occurs (timeout, or error reply from the device), the error parameter is set to a non-zero value.

Note that the ip parameter only holds the last octet of the IP. It is assumed and required that the ezeio and the Modbus server is on the same /24 subnet.
IP configuration is handled via the system settings.

Do not use Modbus/TCP on public networks. It is not a secure protocol.

<WRAP center round important 60%>
Using this command in the user script will disable any system drivers using Modbus to avoid conflicts.
</WRAP>


=== Parameters ===

| ''ip'' | Last octet of the modbus server |
| ''unitid'' | Modbus/TCP unit address (0-255) |
| ''cmd'' | The Modbus command, see below |
| ''reg'' | The register physical address |
| ''format'' | Register type, see below. Optional, defaults to UINT16 |
| ''error'' | Variable to receive the result code. Optional. |

=== Modbus commands ===

| ''MB_COIL'' | Read coil (Modbus command 1) |
| ''MB_DISCRETE'' | Read discrete input (Modbus command 2) |
| ''MB_HOLDING'' | Read holding register (Modbus command 3) |
| ''MB_INPUT'' | Read input register (Modbus command 4) |

=== Register types ===

| ''BT_INT8'' | 8 bit integer, signed |
| ''BT_UINT8'' | 8 bit integer, unsigned |
| ''BT_INT16'' | 16 bit integer, signed |
| ''BT_INT16LE'' | 16 bit integer, signed, byte swapped |
| ''BT_UINT16'' | 16 bit integer, unsigned |
| ''BT_UINT16LE'' | 16 bit integer, unsigned, byte swapped |
| ''BT_INT32'' | 32 bit integer, signed (2 Modbus registers) |
| ''BT_UINT32'' | 32 bit integer, unsigned* (2 Modbus registers) |
| ''BT_INT32LE'' | 32 bit integer, signed, word flipped (2 Modbus registers) |
| ''BT_UINT32LE'' | 32 bit integer, unsigned*, word flipped (2 Modbus registers) |
| ''BT_INT32BLE'' | 32 bit integer, signed, byte flipped (2 Modbus registers) | |
| ''BT_UINT32BLE'' | 32 bit integer, unigned*, byte flipped (2 Modbus registers) | |
| ''BT_INT32LBE'' | 32 bit integer, signed, byte and word flipped (2 Modbus registers) | |
| ''BT_UINT32LBE'' | 32 bit integer, unigned, byte and word flipped (2 Modbus registers) | |
| ''BT_FLOAT'' | IEEE 754 Floating point (2 Modbus registers). See below. |
| ''BT_FLOATLE'' | IEEE 754 Floating point, word flipped (2 Modbus registers). See below. |
| ''BT_FLOAT64'' | IEEE 754 64 bit Floating point* (4 Modbus registers). See below. |
| ''BT_FLOAT64LE'' | IEEE 754 64 bit Floating point*, word reversed (4 Modbus registers). See below. |

=== Return value ===

The function returns the decoded value as a Pawn cell.

*Note that the return value is always a 32 bit cell. This means that a large 32 bit unsigned value will be represented as a negative number in Pawn.

Floating point return values must be tagged as Float, otherwise they are rounded to an integer.

64 bit floating point values will be converted to the closest 32 bit value.

If there is an error, the return value will be zero, and the error parameter will be set to a non-zero value.

=== Example usage ===

<code javascript>
   new err, x;
   x = MBTCP_Read( 105, 1, MB_HOLDING, 101, BT_INT16, err );
   if(err == 0) {
     // x holds the value of holding register 40102 (logical addressing)
   }
</code>

=== Example usage with floating point===

<code javascript>
   new err, Float:x;
   x = Float:MBTCP_Read( 105, 1, MB_HOLDING, 201, BT_FLOAT, err );
   if(err == 0) {
     // x holds the Float-value of holding registers 40202,40203 (logical addressing)
   }
</code>

<WRAP center round important 60%>
Modbus communication is non-trivial. Please refer to the Modbus documentation at https://modbus.org. eze System can't assist with questions related to third party devices. We strongly recommend using our developed and tested drivers for any deployed systems. The functions described here should only be used for testing.
</WRAP>