FieldTalk^™ Modbus^® Master Protocol Library
C++ Editions

MbusAsciiMasterProtocol Class Reference
[Serial Protocols]

Inheritance diagram for MbusAsciiMasterProtocol:

Collaboration diagram for MbusAsciiMasterProtocol:

List of all members.

Detailed Description

Modbus ASCII Master Protocol class.

This class realizes the Modbus ASCII master protocol. 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 Data and Control Functions for all Protocol Flavours.

It is possible to instantiate multiple instances of this class for establishing multiple connections on different serial ports (They should be executed in separate threads).

Version:: 1.1

See also:: mbusmaster
MbusSerialMasterProtocol, MbusMasterFunctions


Specialised Serial Port Management Functions
virtual int	openProtocol (const char *const portName, long baudRate, int dataBits, int stopBits, int parity)
	Opens a Modbus ASCII protocol and the associated serial port with specific port parameters.
virtual int	openProtocol (const char *const portName, long baudRate)
	Opens a Modbus ASCII protocol and the associated serial port with default port parameters.
Serial Port Management Functions
virtual void	closeProtocol ()
	Closes the serial port and releases any system resources associated with the port.
virtual int	isOpen ()
	Returns whether the protocol is open or not.
virtual int	enableRs485Mode (int rtsDelay)
	Enables RS485 mode.
Class 0 Modbus Functions
int	writeMultipleRegisters (int slaveAddr, int startRef, const short regArr[], int refCnt)
	Modbus function 16 (10 hex), Preset Multiple Registers/Write Multiple Registers.
int	writeMultipleLongInts (int slaveAddr, int startRef, const long int32Arr[], int refCnt)
	Modbus function 16 (10 hex) for 32-bit long int data types, Preset Multiple Registers/Write Multiple Registers with long int data.
int	writeMultipleMod10000 (int slaveAddr, int startRef, const long int32Arr[], int refCnt)
	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.
int	writeMultipleFloats (int slaveAddr, int startRef, const float float32Arr[], int refCnt)
	Modbus function 16 (10 hex) for 32-bit float data types, Preset Multiple Registers/Write Multiple Registers with float data.
int	readMultipleRegisters (int slaveAddr, int startRef, short regArr[], int refCnt)
	Modbus function 3 (03 hex), Read Holding Registers/Read Multiple Registers.
int	readMultipleLongInts (int slaveAddr, int startRef, long int32Arr[], int refCnt)
	Modbus function 3 (03 hex) for 32-bit long int data types, Read Holding Registers/Read Multiple Registers as long int data.
int	readMultipleMod10000 (int slaveAddr, int startRef, long int32Arr[], int refCnt)
	Modbus function 3 (03 hex) for 32-bit modulo-10000 long int data types, Read Holding Registers/Read Multiple Registers as modulo-10000 long int data.
int	readMultipleFloats (int slaveAddr, int startRef, float float32Arr[], int refCnt)
	Modbus function 3 (03 hex) for 32-bit float data types, Read Holding Registers/Read Multiple Registers as float data.
Class 1 Modbus Functions
int	readCoils (int slaveAddr, int startRef, int bitArr[], int refCnt)
	Modbus function 1 (01 hex), Read Coil Status/Read Coils.
int	readInputDiscretes (int slaveAddr, int startRef, int bitArr[], int refCnt)
	Modbus function 2 (02 hex), Read Inputs Status/Read Input Discretes.
int	readInputRegisters (int slaveAddr, int startRef, short regArr[], int refCnt)
	Modbus function 4 (04 hex), Read Input Registers.
int	readInputLongInts (int slaveAddr, int startRef, long int32Arr[], int refCnt)
	Modbus function 4 (04 hex) for 32-bit long int data types, Read Input Registers as long int data.
int	readInputMod10000 (int slaveAddr, int startRef, long int32Arr[], int refCnt)
	Modbus function 4 (04 hex) for 32-bit modulo-10000 long int data types, Read Input Registers as modulo-10000 long int data.
int	readInputFloats (int slaveAddr, int startRef, float float32Arr[], int refCnt)
	Modbus function 4 (04 hex) for 32-bit float data types, Read Input Registers as float data.
int	writeCoil (int slaveAddr, int bitAddr, int bitVal)
	Modbus function 5 (05 hex), Force Single Coil/Write Coil.
int	writeSingleRegister (int slaveAddr, int regAddr, short regVal)
	Modbus function 6 (06 hex), Preset Single Register/Write Single Register.
int	readExceptionStatus (int slaveAddr, unsigned char *statusByte)
	Modbus function 7 (07 hex), Read Exception Status.
Class 2 Modbus Functions
int	forceMultipleCoils (int slaveAddr, int startRef, const int bitArr[], int refCnt)
	Modbus function 15 (0F hex), Force Multiple Coils.
int	maskWriteRegister (int slaveAddr, int regAddr, unsigned short andMask, unsigned short orMask)
	Modbus function 22 (16 hex), Mask Write Register.
int	readWriteRegisters (int slaveAddr, int readRef, short readArr[], int readCnt, int writeRef, const short writeArr[], int writeCnt)
	Modbus function 23 (17 hex), Read/Write Registers.
Protocol Configuration
int	setTimeout (int timeOut)
	Configures time-out.
int	getTimeout ()
	Returns the time-out value.
int	setPollDelay (int pollDelay)
	Configures poll delay.
int	getPollDelay ()
	Returns the poll delay time.
int	setRetryCnt (int retryCnt)
	Configures the automatic retry setting.
int	getRetryCnt ()
	Returns the automatic retry count.
Transmission Statistic Functions
unsigned long	getTotalCounter ()
	Returns how often a message transfer has been executed.
void	resetTotalCounter ()
	Resets total message transfer counter.
unsigned long	getSuccessCounter ()
	Returns how often a message transfer was successful.
void	resetSuccessCounter ()
	Resets successful message transfer counter.
Word Order Configuration
void	configureBigEndianInts ()
	Configures int data type functions to do a word swap.
void	configureSwappedFloats ()
	Configures float data type functions to do a word swap.
void	configureLittleEndianInts ()
	Configures int data type functions not to do a word swap.
void	configureIeeeFloats ()
	Configures float data type functions not to do a word swap.
Public Types
enum	{ SER_DATABITS_7 = SerialPort::SER_DATABITS_7, SER_DATABITS_8 = SerialPort::SER_DATABITS_8 }
enum	{ SER_STOPBITS_1 = SerialPort::SER_STOPBITS_1, SER_STOPBITS_2 = SerialPort::SER_STOPBITS_2 }
enum	{ SER_PARITY_NONE = SerialPort::SER_PARITY_NONE, SER_PARITY_EVEN = SerialPort::SER_PARITY_EVEN, SER_PARITY_ODD = SerialPort::SER_PARITY_ODD }
Public Member Functions
	MbusAsciiMasterProtocol ()
	Constructs a MbusAsciiMasterProtocol object and initialises its data.
Static Public Member Functions
char *	getPackageVersion ()
	Returns the package version number.
Protected Types
enum	{ SER_RS232, SER_RS485 }

Member Enumeration Documentation

anonymous enum [inherited]

Enumeration values:

SER_DATABITS_7	7 data bits
SER_DATABITS_8	8 data bits

anonymous enum [inherited]

Enumeration values:

SER_STOPBITS_1	1 stop bit
SER_STOPBITS_2	2 stop bits

anonymous enum [inherited]

Enumeration values:

SER_PARITY_NONE	No parity.
SER_PARITY_EVEN	Even parity.
SER_PARITY_ODD	Odd parity.

anonymous enum [protected, inherited]

Enumeration values:

SER_RS232	RS232 mode w/o RTS/CTS handshake.
SER_RS485	RS485 mode: RTS enables/disables transmitter.

Member Function Documentation

int openProtocol	(	const char *const	portName,
		long	baudRate,
		int	dataBits,
		int	stopBits,
		int	parity
	)	`[virtual]`

Opens a Modbus ASCII protocol and the associated serial port with specific port parameters.

This function opens the serial port. After a port has been opened, data and control functions can be used.

Note:

The default time-out for the data transfer is 1000 ms.

The default poll delay is 0 ms.

Automatic retries are switched off (retry count is 0).

Parameters:

portName	Serial port identifier (e.g. "COM1", "/dev/ser1" or "/dev/ttyS0")
baudRate	The port baudRate in bps (typically 1200 - 19200)
dataBits	SER_DATABITS_7: 7 data bits, SER_DATABITS_8: data bits
stopBits	SER_STOPBITS_1: 1 stop bit, SER_STOPBITS_2: 2 stop bits
parity	SER_PARITY_NONE: no parity, SER_PARITY_ODD: odd parity, SER_PARITY_EVEN: even parity

Returns:: FTALK_SUCCESS on success or error code. See Protocol Errors and Exceptions for a list of error codes.

Reimplemented from MbusSerialMasterProtocol.

int openProtocol	(	const char *const	portName,
		long	baudRate
	)	`[virtual]`

Opens a Modbus ASCII protocol and the associated serial port with default port parameters.

This function opens the serial port with 8 databits, 1 stopbit and no parity. After a port has been opened, data and control functions can be used.

Note:

The default time-out for the data transfer is 1000 ms.

The default poll delay is 0 ms.

Automatic retries are switched off (retry count is 0).

Parameters:

portName	Serial port identifier (e.g. "COM1", "/dev/ser1" or "/dev/ttyS0")
baudRate	The port baudRate in bps (typically 1200 - 9600)

Returns:: FTALK_SUCCESS on success or error code. See Protocol Errors and Exceptions for a list of error codes.

Reimplemented from MbusSerialMasterProtocol.

int isOpen ( ) [virtual, inherited]

Returns whether the protocol is open or not.

Return values:

true	= open
false	= closed

Reimplemented from MbusMasterFunctions.

int enableRs485Mode ( int rtsDelay ) [virtual, inherited]

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.

Remarks:: 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.

Parameters:

rtsDelay

Delay time in ms (Range: 0 - 100000) which applies after the transmit buffer is empty. 0 disables this mode.

Return values:

FTALK_SUCCESS	Success
FTALK_ILLEGAL_ARGUMENT_ERROR	Argument out of range
FTALK_ILLEGAL_STATE_ERROR	Protocol is already open

MbusAsciiMasterProtocol Class Reference [Serial Protocols]

Detailed Description

Specialised Serial Port Management Functions

Serial Port Management Functions

Class 0 Modbus Functions

Class 1 Modbus Functions

Class 2 Modbus Functions

Protocol Configuration

Transmission Statistic Functions

Word Order Configuration

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Member Enumeration Documentation

Member Function Documentation

MbusAsciiMasterProtocol Class Reference
[Serial Protocols]