mbusmasterfunctions.pas

ModBus Communications Libraries for Delphi

(**
 * Modbus function 15 (0F hex),
 * Force Multiple Coils.
 *
 * Writes binary values into a sequence of discrete outputs
 * (coils, 0:00000 table).
 *
 * @param slaveAddr Modbus address of slave device or unit
 * identifier (Range: 1 - 255)
 * @param startRef Start reference (Range: 1 - $10000)
 * @param bitArr  Buffer which contains the data to be sent. The length
 * of the array determines how many coils are written (Range: 1-800).
 * @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.forceMultipleCoils(
   slaveAddr: integer; startRef: integer; var bitArr: array of boolean);
var
   intArr: array[0..800-1] of integer;
   i : integer;
   retVal: integer;
begin
   for i := 0 to high(bitArr) do
   begin
      if (bitArr[i])then
         intArr[i] := 1
      else
         intArr[i] := 0;
   end;
   retVal := mbusMaster_forceMultipleCoils(
                mbusHdl, slaveAddr, startRef, addr(intArr), high(bitArr) + 1);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


(**
 * Modbus function 22 (16 hex),
 * Mask Write Register.
 *
 * Masks bits according to an AND & an OR mask into a single output register
 * (holding register, 4:00000 reference). Masking is done as follows:
 * retVal = (currentVal AND andMask) OR (orMask AND andMask)
 *
 * @param slaveAddr Modbus address of slave device or unit
 * identifier (Range: 1 - 255)
 * @param regAddr Register address (Range: 1 - $10000)
 * @param andMask  Mask to be applied as a logic AND to the register
 * @param orMask  Mask to be applied as a logic OR to the register
 * @note No broadcast supported
 *)
procedure TMbusMasterFunctions.maskWriteRegister(
   slaveAddr: integer; regAddr: integer; andMask: word; orMask: word);
var
   retVal: integer;
begin
   retVal := mbusMaster_maskWriteRegister(
                mbusHdl, slaveAddr, regAddr, andMask, orMask);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


(**
 * Modbus function 23 (17 hex),
 * Read/Write Registers.
 *
 * Combines reading and writing of the output registers in one transaction
 * (holding registers, 4:00000 table).
 *
 * @param slaveAddr Modbus address of slave device or unit
 * identifier (Range: 1 - 255)
 * @param readRef Start registers for reading (Range: 1 - $10000)
 * @param readArr Buffer which will contain the data read. The length
 * of the array determines how many registers are read (Range: 1-125).
 * @param writeRef Start registers for writing (Range: 1 - $10000)
 * @param writeArr Buffer with 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
 * @note No broadcast supported
 *)
procedure TMbusMasterFunctions.readWriteRegisters(
   slaveAddr: integer; readRef: integer; out readArr: array of word;
   writeRef: integer; var writeArr: array of word);
var
   retVal: integer;
begin
   retVal := mbusMaster_readWriteRegisters(
                mbusHdl, slaveAddr,
                readRef, addr(readArr), high(readArr) + 1,
                writeRef, addr(writeArr), high(writeArr) + 1);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


(*****************************************************************************
 * Protocol Configuration
 *****************************************************************************)

(**
 * Configures time-out.  This function sets the operation or socket
 * time-out to the specified value.
 *
 * @remark The time-out value is indicative only and not guaranteed to be
 * maintained. How precise it is followed depends on the operating system
 * used, it's scheduling priority and it's system timer resolution.
 * @note A protocol must be closed in order to configure it.
 * @param timeOut Timeout value in ms (Range: 1 - 100000)
 * @exception EIllegalStateError Protocol is already open
 * @exception EIllegalArgumentError A parameter is out of range
 *)
procedure TMbusMasterFunctions.setTimeout(const timeOut: integer);
var
   retVal: integer;
begin
   retVal := mbusMaster_setTimeout(mbusHdl, timeOut);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


(**
 * Returns the time-out value.
 *
 * @remark The time-out value is indicative only and not guaranteed to
 * be maintained. How precise it is followed depends on the operating
 * system used, it's scheduling priority and it's system timer
 * resolution.
 * @return Timeout value in ms
 *)
function TMbusMasterFunctions.getTimeout: integer;
begin
   getTimeout := mbusMaster_getTimeout(mbusHdl);
end;


(**
 * Configures poll delay. This function sets the delay time
 * which applies between two consecutive Modbus read/write.
 * A value of 0 disables the poll delay.
 *
 * @remark The delay value is indicative only and not guaranteed to be
 * maintained. How precise it is followed depends on the operating system
 * used, it's scheduling priority and it's system timer resolution.
 * @note A protocol must be closed in order to configure it.
 * @param pollDelay Delay time in ms (Range: 0 - 100000), 0 disables
 * poll delay
 * @exception EIllegalStateError Protocol is already open
 * @exception EIllegalArgumentError A parameter is out of range
 *)
procedure TMbusMasterFunctions.setPollDelay(const pollDelay: integer);
var
   retVal: integer;
begin
   retVal := mbusMaster_setPollDelay(mbusHdl, pollDelay);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


(**
 * Returns the poll delay time.
 *
 * @return Delay time in ms, 0 if poll delay is switched off
 *)
function TMbusMasterFunctions.getPollDelay: integer;
begin
   getPollDelay := mbusMaster_getPollDelay(mbusHdl);
end;


(**
 * Configures the automatic retry setting.
 * A value of 0 disables any automatic retries.
 * @note A protocol must be closed in order to configure it.
 *
 * @param retryCnt Retry count (Range: 0 - 10), 0 disables retries
 * @exception EIllegalStateError Protocol is already open
 * @exception EIllegalArgumentError A parameter is out of range
 *)
procedure TMbusMasterFunctions.setRetryCnt(const retryCnt: integer);
var
   retVal: integer;
begin
   retVal := mbusMaster_setRetryCnt(mbusHdl, retryCnt);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


(**
 * Returns the automatic retry count.
 *
 * @return Retry count
 *)
function TMbusMasterFunctions.getRetryCnt: integer;
begin
   getRetryCnt := mbusMaster_getRetryCnt(mbusHdl);
end;


(*****************************************************************************
 * Transmission Statistic Functions
 *****************************************************************************)

(**
 * Returns how often a message transfer has been executed.
 *
 * @return Counter value
 *)
function TMbusMasterFunctions.getTotalCounter: cardinal;
begin
   getTotalCounter := mbusMaster_getTotalCounter(mbusHdl);
end;


(**
 * Resets total message transfer counter.
 *)
procedure TMbusMasterFunctions.resetTotalCounter;
begin
   mbusMaster_resetTotalCounter(mbusHdl);
end;


(**
 * Returns how often a message transfer was successful.
 *
 * @return Counter value
 *)
function TMbusMasterFunctions.getSuccessCounter: cardinal;
begin
   getSuccessCounter := mbusMaster_getSuccessCounter(mbusHdl);
end;


(**
 * Resets successful message transfer counter.
 *)
procedure TMbusMasterFunctions.resetSuccessCounter;
begin
   mbusMaster_resetSuccessCounter(mbusHdl);
end;


(*****************************************************************************
 * Word Order Configuration
 *****************************************************************************)

(**
 * Configures int data type functions to do a word swap.
 *
 * Modbus is using little-endian word order for 32-bit values. The data
 * transfer functions operating upon 32-bit int data types can be
 * configured to do a word swap which enables them to read 32-bit data
 * correctly from a big-endian machine.
 *)
procedure TMbusMasterFunctions.configureBigEndianInts;
begin
   mbusMaster_configureBigEndianInts(mbusHdl);
end;


(**
 * Configures float data type functions to do a word swap.
 *
 * The data functions operating upon 32-bit float data
 * types can be configured to do a word swap.
 * @note Most platforms store floats in IEEE 754 little-endian order
 * which does not need a word swap.
 *)
procedure TMbusMasterFunctions.configureSwappedFloats;
begin
   mbusMaster_configureSwappedFloats(mbusHdl);
end;


(**
 * Configures int data type functions <i>not</i> to do a word swap. This is
 * the default.
 *)
procedure TMbusMasterFunctions.configureLittleEndianInts;
begin
   mbusMaster_configureLittleEndianInts(mbusHdl);
end;


(**
 * Configures float data type functions <i>not</i> to do a word swap. This
 * is the default.
 *)
procedure TMbusMasterFunctions.configureIeeeFloats;
begin
   mbusMaster_configureIeeeFloats(mbusHdl);
end;


(**
 * Sets BigEndianInts property.
 *
 * @param Property value
 *)
procedure TMbusMasterFunctions.setBigEndianInts(val: boolean);
begin
   if val then
      configureBigEndianInts
   else
      configureLittleEndianInts;
   fSwapInts := val;
end;


(**
 * Sets SwappedFloats property.
 *
 * @param Property value
 *)
procedure TMbusMasterFunctions.setSwappedFloats(val: boolean);
begin
   if val then
      configureSwappedFloats
   else
      configureIeeeFloats;
   fSwapFloats := val;
end;


(*****************************************************************************
 * Utility routines
 *****************************************************************************)

(**
 * Returns whether the protocol is open or not.
 *
 * @retval true = open
 * @retval false = closed
 *)
function TMbusMasterFunctions.isOpen(): boolean;
begin
   isOpen := (mbusMaster_isOpen(mbusHdl) = 1);
end;


(**
 * Closes an open protocol including any associated communication
 * resources (COM ports or sockets).
 *)
procedure TMbusMasterFunctions.closeProtocol;
begin
   mbusMaster_closeProtocol(mbusHdl);
end;


(**
 * Returns the package version number.
 *
 * @return Package version string
 * @ingroup mbusmaster
 *)
class function TMbusMasterFunctions.getPackageVersion: string;
begin
   getPackageVersion := widestring(mbusMaster_getPackageVersion);
end;


end.