CommunicationProtocol

class CommunicationProtocol : public QObject

Represents a communication interface for a HardwareObject.

The CommunicationProtocol is a light wrapper around a QIODevice (if appropriate) which handles the actual communication. Extra features are available for customizing the communication and executing common patterns (queries, timeouts, parsing replies with termination characters, etc).

CommunicationProtocol is an interface class; subclasses must implement the _device() function which returns the underlying QIODevice (which may safely be nullptr if no such device exists). The device itself should be created in the initialize() function, which must also be implemented in a subclass. For instance, Rs232Instrument and TcpInstrument both return pointers to their underlying QSerialPort and QTcpSocket devices, while the other implementations return nullptr. The _device() function itself may be called externally if direct access to the QIODevice is needed (i.e., if the QIODevice functionality is not exposed by the wrapper), and the device() template function can be called to conveniently cast to a derived type. For example, if the device is a QTcpSocket:

CommunicationProtocol *comm = new TcpInstrument("key");
comm->initialize();
auto socket = comm->device<QTcpSocket>();
//socket is now a QTcpSocket*

auto socket2 = comm->device<QSerialPort>();
//socket2 is nullptr because comm is a TcpInstrument

CommunicationProtocol provides 3 convenience functions with default implementations that may be extended or overwritten by subclasses:

writeCmd() writes an ASCII string to the QIODevice
writeBinary() writes binary data to the QIODevice
queryCmd() writes a command to the device and reads a response.

The read behavior can be set by a call to setReadOptions, which allows for specifying a query timeout and query termination character(s) that are used to detect the end of a message.

Subclassed by CustomInstrument, GpibInstrument, Rs232Instrument, TcpInstrument, VirtualInstrument

Public Types

enum CommType

CommunicationProtocol options.

Used by HardwareObject to determine which subclass to create.

Values:

enumerator Virtual

enumerator Tcp

enumerator Rs232

enumerator Gpib

enumerator Custom

enumerator None

Public Functions

explicit CommunicationProtocol(QString key, QObject *parent = nullptr)

Constructor.

Parameters:

key – Key assigned to ::d_key
parent – QObject parent

virtual ~CommunicationProtocol(): Destructor. Does nothing.

virtual bool writeCmd(QString cmd)

Writes cmd to the device as ASCII-encoded data.

This function can be safely called even if the device is nullptr.

Parameters:: cmd – Data to write
Returns:: Whether data was written successfully

virtual bool writeBinary(QByteArray dat)

Writes dat to the device as binary data.

This function can be safely called even if the device is nullptr

Parameters:: dat – Data to write
Returns:: Whether data was written successfully

virtual QByteArray queryCmd(QString cmd, bool suppressError = false)

Writes cmd to the device and attempts to read a response.

This function can be safely called even if the device is nullptr. The settings used in the read portion of this function should be set using setReadOptions(). By default, a hardwareFailure() signal is emitted if there is a problem reading or writing data. This signal can be blocked by setting suppressError to true. This may be useful if intermiitent failures are expected and are handled by the caller.

Parameters:

cmd –
suppressError –

Returns:

Repsonse from device

virtual QByteArray readBytes(qint64 n, bool suppressError = false)

Reads n bytes from device, respecting timeout.

Parameters:

n – Number of bytes to read
suppressError – If true, no failure signal will be emitted if all bytes are not read

Returns:

Bytes read

virtual QIODevice *_device() = 0

Returns a pointer to the underlying device.

Returns:: QIODevice pointer or nullptr

template<typename T> inline T *device()

Convenience function for casting QIODevice to type T.

Returns:: Pointer to device of type T* or nullptr

void setErrorString(const QString str)

Sets contents of error string.

Parameters:: Error – message

QString errorString()

Returns last error and clears the error string.

Returns:: Error message

inline void setReadOptions(int tmo, bool useTermChar = false, QByteArray termChar = QByteArray())

Convenience function for setting read options.

Parameters:

tmo – Read timeout, in ms
useTermChar – Whether to look for termination characters at the end of a message
termChar – Termination character(s)

Public Members

const QString d_key: Key used to identify communication protocol. Not currently used.

Public Slots

bool bcTestConnection()

Attempts to open the QIODevice.

This function calls testConnection() and grabs the error string if the call fails.

Returns:: Whether the QIODevice was opened successfully

virtual void initialize() = 0: Creates the QIODevice.

Signals

void logMessage(QString, LogHandler::MessageCode = LogHandler::Normal)

Sends message to Log for printing.

Parameters:

QString – Message
LogHandler::MessageCode – Type of message

void hardwareFailure()

Emitted when a failure occurs with the QIODevice.