mbusserialmasterprotocol.pas

ModBus Communications Libraries for Delphi

(**
 * @internal
 * @file MbusSerialMasterProtocol.pas
 *
 * @if NOTICE
 *
 * $Id: MbusSerialMasterProtocol.pas,v 1.7 2005/07/25 22:41:01 henrik Exp $
 *
 * Copyright (c) 2003-2005 FOCUS Software Engineering Pty Ltd, Australia.
 * All rights reserved. <www.focus-sw.com>
 *
 * USE OF THIS SOFTWARE IS GOVERNED BY THE TERMS AND CONDITIONS OF A
 * SEPARATE LICENSE STATEMENT AND LIMITED WARRANTY.
 *
 * IN PARTICULAR, YOU WILL INDEMNIFY AND HOLD FOCUS SOFTWARE ENGINEERING,
 * ITS RELATED COMPANIES AND ITS SUPPLIERS, HARMLESS FROM AND AGAINST ANY
 * CLAIMS OR LIABILITIES ARISING OUT OF THE USE, REPRODUCTION, OR
 * DISTRIBUTION OF YOUR PROGRAMS, INCLUDING ANY CLAIMS OR LIABILITIES
 * ARISING OUT OF OR RESULTING FROM THE USE, MODIFICATION, OR DISTRIBUTION
 * OF PROGRAMS OR FILES CREATED FROM, BASED ON, AND/OR DERIVED FROM THIS
 * SOURCE CODE FILE.
 *
 * @endif
 *)


unit MbusSerialMasterProtocol;


(*****************************************************************************
 * Interface
 *****************************************************************************)

interface

uses
   Classes,
   MbusMasterFunctions;


const
   SER_DATABITS_7  = 7; ///< 7 data bits
   SER_DATABITS_8  = 8; ///< 8 data bits
   SER_STOPBITS_1  = 1; ///< 1 stop bit
   SER_STOPBITS_2  = 2; ///< 2 stop bits
   SER_PARITY_NONE = 0; ///< No parity
   SER_PARITY_ODD  = 1; ///< Odd parity
   SER_PARITY_EVEN = 2; ///< Even parity


(*****************************************************************************
 * TMbusSerialMasterProtocol class declaration
 *****************************************************************************)

(**
 * @brief Base class for serial serial master protocols
 *
 * This base class realises the Modbus serial master protocols. It provides
 * functions to open and to close serial port as well as data and control
 * functions which can be used at any time after the protocol has been
 * opened. The data and control functions are organized different
 * conformance classes. For a more detailed description of the data and
 * control functions see section @ref mbusmaster.
 *
 * It is possible to instantiate multiple instances for establishing
 * multiple connections on different serial ports (They should be executed
 * in separate threads).
 *
 * @version 1.1
 * @see mbusmaster
 * @see MbusMasterFunctions
 *)
type
   TMbusSerialMasterProtocol = class(TMbusMasterFunctions)

    protected

      fPortName: string;
      fBaudRate: longint;
      fDataBits: integer;
      fStopBits: integer;
      fParity: integer;


    public

      constructor Create(aOwner: TComponent); override;

      (**
       * @name Serial Port Management Functions
       *)
      //@{

      function openProtocol(): Integer;

      procedure enableRs485Mode(rtsDelay: integer);


   published

      (**
       * Serial port identifier property (eg "COM1")
       *
       * @note A protocol must be closed in order to configure it.
       *)
      property portName: string read fPortName write fPortName;

      (**
       * Baud rate property in bps (typically 1200 - 115200, maximum value depends on UART hardware)
       *
       * @note A protocol must be closed in order to configure it.
       *)
      property baudRate: longint read fBaudRate write fBaudRate default 9600;

      (**
       * Data bits property. SER_DATABITS_7: 7 data bits (ASCII protocol only),
       * SER_DATABITS_8: 8 data bits
       *
       * @note A protocol must be closed in order to configure it.
       *)
      property dataBits: integer read fDataBits write fDataBits
         default SER_DATABITS_8;

      (**
       * Stop bits property. SER_STOPBITS_1: 1 stop bit,
       *  SER_STOPBITS_2: 2 stop bits
       *
       * @note A protocol must be closed in order to configure it.
       *)
      property stopBits: integer read fStopBits write fStopBits
         default SER_STOPBITS_1;

      (**
       * Parity property. SER_PARITY_NONE: no parity,
       * SER_PARITY_ODD: odd parity, SER_PARITY_EVEN: even parity
       *
       * @note A protocol must be closed in order to configure it.
       *)
      property parity: integer read fParity write fParity
         default SER_PARITY_NONE;

      //@}

   end;


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

implementation

uses
   BusProtocolExceptions;


(*****************************************************************************
 * DLL stub functions
 *****************************************************************************)

function mbusMaster_openSerialProtocol(
   mbusHdl: pointer; portName: pwidechar; baudRate: longint;
   dataBits: integer; stopBits: integer; parity: integer): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_openSerialProtocol@24';

function mbusMaster_enableRs485Mode(
   mbusHdl: pointer; rtsDelay: integer): integer;
   stdcall; external 'libmbusmaster.dll' name '_mbusMaster_enableRs485Mode@8';


(*****************************************************************************
 * TMbusSerialMasterProtocol class implementation
 *****************************************************************************)

(**
 * @defgroup mbusmasterserial Serial Protocols
 *
 * The two serial protocol flavours are implemented in the
 * MbusRtuMasterProtocol and MbusAsciiMasterProtocol class. These classes
 * provide functions to open and to close serial port as well as data and
 * control functions which can be used at any time after a protocol has
 * been opened. The data and control functions are organized different
 * conformance classes. For a more detailed description of the data and
 * control functions see section @ref mbusmaster.
 *
 * Using multiple instances of a MbusRtuMasterProtocol or
 * MbusAsciiMasterProtocol class enables concurrent protocol transfers on
 * multiple COM ports (They should be executed in separate threads).
 *
 * See sections @ref mbusrtuprotocol and @ref mbusasciiprotocol for some
 * background information about the two serial Modbus protocols.
 *
 * See section @ref serialintegrate for an example how to use the
 * MbusRtuMasterProtocol class.
 *)
//@{
//@}


(**
 * Constructs a TMbusSerialMasterProtocol object and initialises its data.
 *)
constructor TMbusSerialMasterProtocol.Create(aOwner: TComponent);
begin
   inherited Create(aOwner);
   fPortName := 'COM1';
end;


(**
 * Opens a serial Modbus protocol and the associated serial port with
 * the port parameters configured via properties.
 *
 * This function opens the serial port. After a port has been
 * opened, data and control functions can be used.
 *
 * @exception EInOutError An I/O error occurred
 * @exception EOpenErr The serial port does not exist
 * @exception EPortAlreadyOpen Port is already used by somedbody else
 * @exception EPortNoAccess No permission to access serial
 * @exception EIllegalArgumentError A parameter is invalid
 *)
function TMbusSerialMasterProtocol.openProtocol(): Integer;
//var
//   retVal: integer;
begin
   Result := mbusMaster_openSerialProtocol(mbusHdl, pwidechar(widestring(fPortName)),
                fBaudRate, fDataBits, fStopBits, fParity);
   //if retVal <> 0 then
   //  Exit;
      //raise exceptionFactory(retVal);
end;


(**
 * Enables RS485 mode.
 *
 * In RS485 mode the RTS signal can be used to enable and disable the
 * transmitter of a RS232/RS485 converter. The RTS signal is asserted
 * before sending data. It is cleared after the transmit buffer has been
 * emptied and in addition the specified delay time has elapsed. The delay
 * time is necessary because even the transmit buffer is already empty, the
 * UART's FIFO will still contain unsent characters.
 *
 * @warning The use of RTS controlled RS232/RS485 converters should be
 * avoided if possible. It is difficult to determine the exact time when to
 * switch off the transmitter with non real-time operating systems like
 * Windows and Linux. If it is switched off to early characters might still
 * sit in the FIFO or the transmit register of the UART and these
 * characters will be lost. Hence the slave will not recognize the
 * message. On the other hand if it is switched off too late then the
 * slave's message is corrupted and the master will not recognize the
 * message.
 *
 * @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 rtsDelay Delay time in ms (Range: 0 - 100000) which applies after
 * the transmit buffer is empty. 0 disables this mode.
 * @exception EIllegalStateError Protocol is already open
 * @exception EIllegalArgumentError A parameter is out of range
 *)
procedure TMbusSerialMasterProtocol.enableRs485Mode(rtsDelay: integer);
var
   retVal: integer;
begin
   retVal := mbusMaster_enableRs485Mode(mbusHdl, rtsDelay);
   if retVal <> 0 then
      raise exceptionFactory(retVal);
end;


end.