mbusmasterfunctions.pas

ModBus Communications Libraries for Delphi

   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_writeSingleRegister@16';

function mbusMaster_readExceptionStatus(
   mbusHdl: pointer; slaveAddr: integer;
   var statusByte: byte): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_readExceptionStatus@12';

function mbusMaster_forceMultipleCoils(
   mbusHdl: pointer; slaveAddr: integer; startRef: integer;
   refArrPtr: pointer; refCnt: integer): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_forceMultipleCoils@20';

function mbusMaster_maskWriteRegister(
   mbusHdl: pointer; slaveAddr: integer; regAddr: integer;
   andMask: word; orMask: word): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_maskWriteRegister@20';

function mbusMaster_readWriteRegisters(
   mbusHdl: pointer; slaveAddr: integer;
   readRef: integer; readArrPtr: pointer; readCnt: integer;
   writeRef: integer; writeArrPtr: pointer; writeCnt: integer): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_readWriteRegisters@32';

function mbusMaster_setTimeout(
   mbusHdl: pointer; timeOut: integer): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_setTimeout@8';

function mbusMaster_getTimeout(mbusHdl: pointer): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_getTimeout@4';

function mbusMaster_setPollDelay(
mbusHdl: pointer; pollDelay: integer): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_setPollDelay@8';

function mbusMaster_getPollDelay(mbusHdl: pointer): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_getPollDelay@4';

function mbusMaster_setRetryCnt(
   mbusHdl: pointer; retryCnt: integer): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_setRetryCnt@8';

function mbusMaster_getRetryCnt(mbusHdl: pointer): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_getRetryCnt@4';

function mbusMaster_getTotalCounter(mbusHdl: pointer): cardinal;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_getTotalCounter@4';

procedure mbusMaster_resetTotalCounter(mbusHdl: pointer);
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_resetTotalCounter@4';

function mbusMaster_getSuccessCounter(mbusHdl: pointer): cardinal;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_getSuccessCounter@4';

procedure mbusMaster_resetSuccessCounter(mbusHdl: pointer);
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_resetSuccessCounter@4';

procedure mbusMaster_configureBigEndianInts(mbusHdl: pointer);
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_configureBigEndianInts@4';

procedure mbusMaster_configureSwappedFloats(mbusHdl: pointer);
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_configureSwappedFloats@4';

procedure mbusMaster_configureLittleEndianInts(mbusHdl: pointer);
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_configureLittleEndianInts@4';

procedure mbusMaster_configureIeeeFloats(mbusHdl: pointer);
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_configureIeeeFloats@4';

function mbusMaster_isOpen(mbusHdl: pointer): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_isOpen@4';

procedure mbusMaster_closeProtocol(mbusHdl: pointer);
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_closeProtocol@4';

function mbusMaster_getPackageVersion: pwidechar;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_getPackageVersion@0';


(*****************************************************************************
 * Implementation
 *****************************************************************************)

implementation

uses
   SysUtils,
   BusProtocolExceptions;


(*****************************************************************************
 * TMbusMasterFunctions class implementation
 *****************************************************************************)

(**
 * @defgroup mbusmaster Data and Control Functions for all Protocol Flavours
 *
 * @brief This protocol stack implements the most
 * commonly used Modbus data functions as well as some control
 * functions. The functions to perform PLC program download and other
 * device specific functions are outside the scope of this library.
 *
 * All functions of conformance Class 0 and Class 1 have been
 * implemented. In addition the most frequent used functions of conformance
 * Class 2 have been implemented. This rich function set enables a user to
 * solve nearly every Modbus data transfer problem.
 *
 * The following table lists the available <i>FieldTalk Master Protocol
 * Pack</i> functions:
 *
 * <table>
 *    <tr><td><b>Function Code</b></td><td><b>Current Terminology</b></td>
 *       <td><b>Classic Terminology</b></td></tr>
 *    <tr><td><b>Conformance Class 0</b></td></tr>
 *    <tr><td>3 (03 hex)</td><td>Read Multiple Registers</td>
 *       <td>Read Holding Registers</td></tr>
 *    <tr><td>16 (10 hex)</td><td>Write Multiple Registers</td>
 *       <td>Preset Multiple Registers</td></tr>
 *    <tr><td><b>Conformance Class 1</b></td></tr>
 *    <tr><td>1 (01 hex)</td><td>Read Coils</td><td>Read Coil Status</td></tr>
 *    <tr><td>2 (02 hex)</td><td>Read Inputs Discretes</td>
 *       <td>Read Input Status</td></tr>
 *    <tr><td>4 (04 hex)</td><td>Read Input Registers</td>
 *       <td>Read Input Registers</td></tr>
 *    <tr><td>5 (05 hex)</td><td>Write Coil</td><td>Force Single Coil</td></tr>
 *    <tr><td>6 (06 hex)</td><td>Write Single Register</td>
 *       <td>Preset Single Register</td></tr>
 *    <tr><td>7 (07 hex)</td><td>Read Exception Status</td>
 *       <td>Read Exception Status</td></tr>
 *    <tr><td><b>Conformance Class 2</b></td></tr>
 *    <tr><td>15 (0F hex)</td><td>Force Multiple Coils</td>
 *       <td>Force Multiple Coils</td></tr>
 *    <tr><td>22 (16 hex)</td><td>Mask Write Register</td>
 *       <td>Mask Write Register</td></tr>
 *    <tr><td>23 (17 hex)</td><td>Read/Write Registers</td>
 *        <td>Read/Write Registers</td></tr>
 * </table>
 *
 * @remark When passing register numbers and discrete numbers to
 * <i>FieldTalk</i> functions you have to use the the
 * Modbus register and discrete numbering scheme. See @ref mbusregnumbers.
 * (Internally the functions will deduct 1 from the start register value
 * before transmitting the value to the slave device.)
 *
 * @remark Most slave devices are limiting the amount of registers to be
 * exchanged with the ASCII protocol to be 62 registers or 496
 * discretes. The limitation is based on the fact that the buffer must not
 * exceed 256 bytes.
 *)
//@{
//@}


(**
 * Destructor. Does clean-up and closes an open protocol including any
 * associated communication resources (serial ports or sockets).
 *)
destructor TMbusMasterFunctions.Destroy;
begin
   if mbusHdl <> nil then
      mbusMaster_destroyProtocol(mbusHdl);
   inherited Destroy;
end;


(*****************************************************************************
 * Class 0 Modbus functions
 *****************************************************************************)

(**
 * Modbus function 16 (10 hex),
 * Preset Multiple Registers/Write Multiple Registers.
 *
 * Writes values into a sequence of output registers
 * (holding registers, 4:00000 table).
 *
 * @param slaveAddr Modbus address of slave device or unit
 * identifier (Range: 0 - 255)
 * @param startRef Start register (Range: 1 - $10000)
 * @param regArr Buffer with the data to be sent.The length
 * of the array determines how many registers are written (Range: 1-100).
 * @exception EIllegalStateError Port or connection is closed
 * @exception EInOutError An I/O error occurred
 * @exception EIllegalArgumentError A parameter is out of range
 * @exception EBusProtocolException A protocol failure occurred. See
 * descendants of EBusProtocolException for a more detailed failure list.
 * @note Broadcast supported for serial protocols
 *)
procedure TMbusMasterFunctions.writeMultipleRegisters(
   slaveAddr: integer; startRef: integer; var regArr: array of word);
var
   retVal: integer;
begin
   retVal := mbusMaster_writeMultipleRegisters(mbusHdl, slaveAddr, startRef,
                addr(regArr), high(regArr) + 1);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


(**
 * Modbus function 16 (10 hex) for 32-bit long int data types,
 * Preset Multiple Registers/Write Multiple Registers with
 * long int data.
 *
 * Writes long int values into pairs of output registers
 * (holding registers, 4:00000 table).
 *
 * @remark Modbus does not know about any other data type than discretes
 * and 16-bit registers. Because a long int value is of
 * 32-bit length, it will be transferred as two consecutive
 * 16-bit registers.
 * This means that the amount of registers transferred with this function
 * is twice the amount of int values passed to this function.
 * @param slaveAddr Modbus address of slave device or unit
 * identifier (Range: 0 - 255)
 * @param startRef Start reference (Range: 1 - $10000)
 * @param int32Arr Buffer with the data to be sent. The length
 * of the array determines how many values are read (Range: 1-50).
 * @exception EIllegalStateError Port or connection is closed
 * @exception EInOutError An I/O error occurred
 * @exception EIllegalArgumentError A parameter is out of range
 * @exception EBusProtocolException A protocol failure occurred. See
 * @note Broadcast supported for serial protocols
 *)
procedure TMbusMasterFunctions.writeMultipleLongInts(
   slaveAddr: integer; startRef: integer; var int32Arr: array of integer);
var
   retVal: integer;
begin
   retVal := mbusMaster_writeMultipleLongInts(mbusHdl, slaveAddr, startRef,
                addr(int32Arr), high(int32Arr) + 1);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


(**
 * Modbus function 16 (10 hex) for 32-bit modulo-10000 long int data types,
 * Preset Multiple Registers/Write Multiple Registers with
 * modulo-10000 long int data.
 *
 * Writes long int values into pairs of output registers (holding
 * registers, 4:00000 table) representing a modulo-10000 long int value and
 * performs number format conversion.
 *
 * @remark Modbus does not know about any other data type than discretes
 * and 16-bit registers. Because a modulo-10000 value is of
 * 32-bit length, it will be transferred as two consecutive
 * 16-bit registers.
 * This means that the amount of registers transferred with this function
 * is twice the amount of int values passed to this function.
 * @param slaveAddr Modbus address of slave device or unit
 * identifier (Range: 0 - 255)
 * @param startRef Start reference (Range: 1 - $10000)
 * @param int32Arr Buffer with the data to be sent. The length
 * of the array determines how many values are written (Range: 1-50).
 * @exception EIllegalStateError Port or connection is closed
 * @exception EInOutError An I/O error occurred
 * @exception EIllegalArgumentError A parameter is out of range
 * @exception EBusProtocolException A protocol failure occurred. See
 * @note Broadcast supported for serial protocols
 *)
procedure TMbusMasterFunctions.writeMultipleMod10000(
   slaveAddr: integer; startRef: integer; var int32Arr: array of integer);
var
   retVal: integer;
begin
   retVal := mbusMaster_writeMultipleMod10000(mbusHdl, slaveAddr, startRef,
                addr(int32Arr), high(int32Arr) + 1);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


(**
 * Modbus function 16 (10 hex) for 32-bit float data types,
 * Preset Multiple Registers/Write Multiple Registers with float data.
 *
 * Writes float values into pairs of output registers (holding
 * registers, 4:00000 table).
 *
 * @remark Modbus does not know about any
 * other data type than discretes and 16-bit registers. Because a float
 * value is of 32-bit length, it will be transferred as two consecutive
 * 16-bit registers.  This means that the amount of registers
 * transferred with this function is twice the amount of float values
 * passed to this function.
 * @param slaveAddr Modbus address of slave device or unit
 * identifier (Range: 0 - 255)
 * @param startRef Start reference (Range: 1 - $10000)
 * @param float32Arr Buffer with the data to be sent. The length
 * of the array determines how many values are written (Range: 1-50).
 * @exception EIllegalStateError Port or connection is closed
 * @exception EInOutError An I/O error occurred
 * @exception EIllegalArgumentError A parameter is out of range
 * @exception EBusProtocolException A protocol failure occurred. See
 * @note Broadcast supported for serial protocols
 *)
procedure TMbusMasterFunctions.writeMultipleFloats(
   slaveAddr: integer; startRef: integer; var float32Arr: array of single);
var
   retVal: integer;
begin
   retVal := mbusMaster_writeMultipleFloats(mbusHdl, slaveAddr, startRef,
                addr(float32Arr), high(float32Arr) + 1);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


(**
 * Modbus function 3 (03 hex),
 * Read Holding Registers/Read Multiple Registers.
 *
 * Reads the contents of the output registers
 * (holding registers, 4:00000 table).
 *
 * @param slaveAddr Modbus address of slave device or unit
 * identifier (Range: 1 - 255)
 * @param startRef Start register (Range: 1 - $10000)
 * @param regArr Buffer which will be filled with the data read. The length
 * of the array determines how many registers are read (Range: 1-125).
 * @exception EIllegalStateError Port or connection is closed
 * @exception EInOutError An I/O error occurred
 * @exception EIllegalArgumentError A parameter is out of range
 * @exception EBusProtocolException A protocol failure occurred. See
 * @note No broadcast supported
 *)
procedure TMbusMasterFunctions.readMultipleRegisters(
   slaveAddr: integer; startRef: integer; out regArr: array of word);
var
   retVal: integer;
begin
   retVal := mbusMaster_readMultipleRegisters(mbusHdl, slaveAddr, startRef,
                addr(regArr), high(regArr) + 1);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


(**
 * Modbus function 3 (03 hex) for 32-bit long int data types,
 * Read Holding Registers/Read Multiple Registers as long int data.
 *
 * Reads the contents of pairs of consecutive output registers (holding
 * registers, 4:00000 table) into 32-bit long int values.
 *
 * @remark Modbus does not know about any other data type than discretes
 * and 16-bit registers. Because a long int value is of
 * 32-bit length, it will be transferred as two consecutive
 * 16-bit registers.
 * This means that the amount of registers transferred with this function
 * is twice the amount of int values passed to this function.
 * @param slaveAddr Modbus address of slave device or unit
 * identifier (Range: 1 - 255)
 * @param startRef Start reference (Range: 1 - $10000)
 * @param int32Arr Buffer which will be filled with the data read. The length
 * of the array determines how many values are read (Range: 1-62).
 * @exception EIllegalStateError Port or connection is closed
 * @exception EInOutError An I/O error occurred
 * @exception EIllegalArgumentError A parameter is out of range
 * @exception EBusProtocolException A protocol failure occurred. See
 * @note No broadcast supported
 *)
procedure TMbusMasterFunctions.readMultipleLongInts(
   slaveAddr: integer; startRef: integer; out int32Arr: array of integer);
var
   retVal: integer;
begin
   retVal := mbusMaster_readMultipleLongInts(mbusHdl, slaveAddr, startRef,
                addr(int32Arr), high(int32Arr) + 1);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


(**
 * Modbus function 3 (03 hex) for 32-bit modulo-10000 long int data types,