==== MBRTU_Read ====

Read a single register from a Modbus/RTU device

=== Description ===

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

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

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

=== Parameters ===

| ''unitid'' | Modbus/RTU device bus address (1-254) |
| ''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 = MBRTU_Read( 5, 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:MBRTU_Read( 5, 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>